<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Fri, Aug 12, 2016 at 3:29 AM, Akihiro Motoki <span dir="ltr"><<a href="mailto:amotoki@gmail.com" target="_blank">amotoki@gmail.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">this mail focuses on neutron-specific topics. I dropped cinder and ironic tags.<br>
<br>
2016-08-11 23:52 GMT+09:00 Anne Gentle <<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a><wbr>>:<br>
><br>
><br>
> On Wed, Aug 10, 2016 at 2:49 PM, Anne Gentle <<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a><wbr>><br>
> wrote:<br>
>><br>
>> Hi all,<br>
>> I wanted to report on status and answer any questions you all have about<br>
>> the API reference and guide publishing process.<br>
>><br>
>> The expectation is that we provide all OpenStack API information on<br>
>> <a href="http://developer.openstack.org" rel="noreferrer" target="_blank">developer.openstack.org</a>. In order to meet that goal, it's simplest for now<br>
>> to have all projects use the RST+YAML+openstackdocstheme+<wbr>os-api-ref<br>
>> extension tooling so that users see available OpenStack APIs in a sidebar<br>
>> navigation drop-down list.<br>
>><br>
>> --Migration--<br>
>> The current status for migration is that all WADL content is migrated<br>
>> except for trove. There is a patch in progress and I'm in contact with the<br>
>> team to assist in any way. <a href="https://review.openstack.org/#/c/316381/" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/316381/</a><br>
>><br>
>> --Theme, extension, release requirements--<br>
>> The current status for the theme, navigation, and Sphinx extension tooling<br>
>> is contained in the latest post from Graham proposing a solution for the<br>
>> release number switchover and offers to help teams as needed:<br>
>> <a href="http://lists.openstack.org/pipermail/openstack-dev/2016-August/101112.html" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>pipermail/openstack-dev/2016-<wbr>August/101112.html</a> I<br>
>> hope to meet the requirements deadline to get those changes landed.<br>
>> Requirements freeze is Aug 29.<br>
>><br>
>> --Project coverage--<br>
>> The current status for project coverage is that these projects are now<br>
>> using the RST+YAML in-tree workflow and tools and publishing to<br>
>> <a href="http://developer.openstack.org/api-ref/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/</a><servicename> so they will be<br>
>> included in the upcoming API navigation sidebar intended to span all<br>
>> OpenStack APIs:<br>
>><br>
>> designate <a href="http://developer.openstack.org/api-ref/dns/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/dns/</a><br>
>> glance <a href="http://developer.openstack.org/api-ref/image/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/image/</a><br>
>> heat <a href="http://developer.openstack.org/api-ref/orchestration/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/orchestration/</a><br>
>> ironic <a href="http://developer.openstack.org/api-ref/baremetal/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/baremetal/</a><br>
>> keystone <a href="http://developer.openstack.org/api-ref/identity/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/identity/</a><br>
>> manila <a href="http://developer.openstack.org/api-ref/shared-file-systems/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/shared-file-<wbr>systems/</a><br>
>> neutron-lib <a href="http://developer.openstack.org/api-ref/networking/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/networking/</a><br>
>> nova <a href="http://developer.openstack.org/api-ref/compute/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/compute/</a><br>
>> sahara <a href="http://developer.openstack.org/api-ref/data-processing/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/data-processing/</a><br>
>> senlin <a href="http://developer.openstack.org/api-ref/clustering/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/clustering/</a><br>
>> swift <a href="http://developer.openstack.org/api-ref/object-storage/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/object-storage/</a><br>
>> zaqar <a href="http://developer.openstack.org/api-ref/messaging/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/messaging/</a><br>
>><br>
>> These projects are using the in-tree workflow and common tools, but do not<br>
>> have a publish job in project-config in the jenkins/jobs/projects.yaml file.<br>
>><br>
>> ceilometer<br>
><br>
><br>
> Sorry, in reviewing further today I found another project that does not have<br>
> a publish job but has in-tree source files:<br>
><br>
> cinder<br>
><br>
> Team cinder: can you let me know where you are in your publishing comfort<br>
> level? Please add an api-ref-jobs: line with a target of block-storage to<br>
> jenkins/jobs/projects.yaml in the project-config repo to ensure publishing<br>
> is correct.<br>
><br>
> Another issue is the name of the target directory for the final URL. Team<br>
> ironic can I change your api-ref-jobs: line to bare-metal instead of<br>
> baremetal? It'll be better for search engines and for alignment with the<br>
> other projects URLs: <a href="https://review.openstack.org/354135" rel="noreferrer" target="_blank">https://review.openstack.org/<wbr>354135</a><br>
><br>
> I've also uncovered a problem where a neutron project's API does not have an<br>
> official service name, and am working on a solution but need help from the<br>
> neutron team: <a href="https://review.openstack.org/#/c/351407" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/351407</a><br>
<br>
I followed the discussion in <a href="https://review.openstack.org/#/c/351407" rel="noreferrer" target="_blank">https://review.openstack.org/#<wbr>/c/351407</a><br>
and my understanding of the conclusion is to add API reference source<br>
of neutron stadium projects<br>
to neutron-lib and publish them under<br>
<a href="http://developer.openstack.org/api-ref/networking/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/networking/</a> .<br>
I sounds reasonable to me.<br>
<br>
We can have a dedicated pages for each stadium project like networking-sfc<br>
like api-ref/networking/service-<wbr>function-chaining.<br>
At now all APIs are placed under v2/ directory, but it is not good<br>
both from user and<br>
maintenance perspectives.<br>
<br>
<br>
So, the next thing we need to clarify is what names and directory<br>
structure are appropropriate<br>
from the documentation perspective.<br>
My proposal is to prepare a dedicated directory per networking project<br>
repository.<br>
The directory name should be a function name rather than a project<br>
name. For example,<br>
- neutron => ???<br>
- neutron-lbaas => load-balancer<br>
- neutron-vpnaas => vpn<br>
- neutron-fwaas => firewall<br>
- neutron-dynamic-routing => dynamic-routing<br>
- networking-sfc => service-function-chaining<br>
- networking-l2gw => layer2-gateway<br>
- (networking-bgpvpn) => bgp-vpn<br>
<br>
My remaining open questions are:<br>
<br>
- Is 'v2' directory needed?<br>
  All networking API provided by stadium projects are extensions to<br>
Networking v2 API and "v2" is the only API we have now.<br></blockquote><div><br></div><div>Is that accurate? LBaaS was version 1 something if I recall correctly.</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
  Do we place all APIs from stadium projects under 'v2' directory, or<br>
is 'v2' directory unnecessary?<br></blockquote><div><br></div><div>I think that we want to remain similar across other API definitions, so that it makes sense to have <a href="http://developer.openstack.org/api-ref/image/v2/index.html">http://developer.openstack.org/api-ref/image/v2/index.html</a> for example.</div><div><br></div><div>What is happening now is the use of a v2-ext directory:</div><div><a href="http://developer.openstack.org/api-ref/networking/v2-ext/#fwaas-v2-0-current-fw-firewalls-firewall-policies-firewall-rules">http://developer.openstack.org/api-ref/networking/v2-ext/#fwaas-v2-0-current-fw-firewalls-firewall-policies-firewall-rules</a><br></div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
- what is a good name for main neutron API (provided by 'neutron' repo)?<br></blockquote><div><br></div><div>Armando is suggesting neutron-lib as the doc repo, and Networking API as the name, right? Perhaps I misunderstand you. I don't envision changing that simply because of movement of source files, do you?</div><div><br></div><div>Anne</div><div> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<br>
Any feedback would be appreciated.<br>
<br>
Thanks,<br>
Akihiro<br>
<br>
> Thanks,<br>
> Anne<br>
><br>
>><br>
>><br>
>> --Projects not using common tooling--<br>
>> These projects have API docs but are not yet using the common tooling, as<br>
>> far as I can tell. Because of the user experience, I'm making a judgement<br>
>> call that these cannot be included in the common navigation. I have patched<br>
>> the projects.yaml file in the governance repo with the URLs I could<br>
>> screen-scrape, but if I'm incorrect please do patch the projects.yaml in the<br>
>> governance repo.<br>
>><br>
>> astara<br>
>> cloudkitty<br>
>> congress<br>
>> magnum<br>
>> mistral<br>
>> monasca<br>
>> solum<br>
>> tacker<br>
>> trove<br>
>><br>
>> Please reach out if you have questions or need assistance getting started<br>
>> with the new common tooling, documented here:<br>
>> <a href="http://docs.openstack.org/contributor-guide/api-guides.html" rel="noreferrer" target="_blank">http://docs.openstack.org/<wbr>contributor-guide/api-guides.<wbr>html</a>.<br>
>><br>
>> For searchlight, looking at <a href="http://developer.openstack.org/api-ref/search/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/search/</a><br>
>> they have the build job, but the info is not complete yet.<br>
>><br>
>> One additional project I'm not sure what to do with is networking-nfc,<br>
>> since I'm not sure it is considered a neutron API. Can I get help to sort<br>
>> that question out?<br>
>><br>
>> --Redirects from old pages--<br>
>> We have been adding .htaccess redirects from the old<br>
>> api-ref-servicename.html on <a href="http://developer.openstack.org" rel="noreferrer" target="_blank">developer.openstack.org</a> as teams are comfortable<br>
>> with the accuracy of information and build stability. Please help out by<br>
>> patching the api-site repository's .htaccess file when you are ready to<br>
>> redirect. These projects could be ready for redirects but do not have them:<br>
>><br>
>> designate<br>
>> glance<br>
>> heat<br>
>> sahara<br>
>> senlin<br>
>> swift<br>
>><br>
>> I'm available for questions so please reach out as needed. I hope this<br>
>> covers our current status.<br>
>><br>
>> A million thank yous to everyone who got us this far! Great teamwork,<br>
>> great docs work, great UI work, and great API work everyone.<br>
>> Anne<br>
<span class=""><font color="#888888">>><br>
>> --<br>
>> Anne Gentle<br>
>> <a href="http://www.justwriteclick.com" rel="noreferrer" target="_blank">www.justwriteclick.com</a><br>
><br>
><br>
><br>
><br>
> --<br>
> Anne Gentle<br>
> <a href="http://www.justwriteclick.com" rel="noreferrer" target="_blank">www.justwriteclick.com</a><br>
><br>
> ______________________________<wbr>_________________<br>
> OpenStack-docs mailing list<br>
> <a href="mailto:OpenStack-docs@lists.openstack.org">OpenStack-docs@lists.<wbr>openstack.org</a><br>
> <a href="http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs" rel="noreferrer" target="_blank">http://lists.openstack.org/<wbr>cgi-bin/mailman/listinfo/<wbr>openstack-docs</a><br>
><br>
</font></span></blockquote></div><br><br clear="all"><div><br></div>-- <br><div class="gmail_signature" data-smartmail="gmail_signature"><div dir="ltr"><div><div dir="ltr"><div>Anne Gentle</div><div><a href="http://www.justwriteclick.com" style="font-size:12.8px" target="_blank">www.justwriteclick.com</a><br></div></div></div></div></div>
</div></div>