<div dir="ltr"><br><div class="gmail_extra"><br><div class="gmail_quote">On Thu, Aug 18, 2016 at 3:33 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"><div class=""><div class="h5">2016-08-13 7:36 GMT+09:00 Anne Gentle <<a href="mailto:annegentle@justwriteclick.com">annegentle@justwriteclick.com</a><wbr>>:<br>
><br>
><br>
> On Fri, Aug 12, 2016 at 3:29 AM, Akihiro Motoki <<a href="mailto:amotoki@gmail.com">amotoki@gmail.com</a>> wrote:<br>
>><br>
>> this mail focuses on neutron-specific topics. I dropped cinder and ironic<br>
>> 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<br>
>> > <<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<br>
>> >> 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<br>
>> >> 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<br>
>> >> 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<br>
>> >> 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<br>
>> >> tooling<br>
>> >> is contained in the latest post from Graham proposing a solution for<br>
>> >> the<br>
>> >> release number switchover and offers to help teams as needed:<br>
>> >><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<br>
>> >> not<br>
>> >> have a publish job in project-config in the jenkins/jobs/projects.yaml<br>
>> >> file.<br>
>> >><br>
>> >> ceilometer<br>
>> ><br>
>> ><br>
>> > Sorry, in reviewing further today I found another project that does not<br>
>> > 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<br>
>> > comfort<br>
>> > level? Please add an api-ref-jobs: line with a target of block-storage<br>
>> > to<br>
>> > jenkins/jobs/projects.yaml in the project-config repo to ensure<br>
>> > publishing<br>
>> > is correct.<br>
>> ><br>
>> > Another issue is the name of the target directory for the final URL.<br>
>> > 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<br>
>> > have an<br>
>> > official service name, and am working on a solution but need help from<br>
>> > 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>
><br>
><br>
> Is that accurate? LBaaS was version 1 something if I recall correctly.<br>
<br>
</div></div>Neutron has two versions of LBaaS (v1 and v2) but both of them are<br>
implemented as Networking v2 API extension.<br></blockquote><div><br></div><div>Ah, okay, right. Would <a href="http://developer.openstack.org/api-ref/networking/lbaas/v1">developer.openstack.org/api-ref/networking/lbaas/v1</a> and <a href="http://developer.openstack.org/api-ref/networking/lbaas/v2">developer.openstack.org/api-ref/networking/lbaas/v2</a> work?</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">
<span class=""><br>
>><br>
>>   Do we place all APIs from stadium projects under 'v2' directory, or<br>
>> is 'v2' directory unnecessary?<br>
><br>
><br>
> I think that we want to remain similar across other API definitions, so that<br>
> it makes sense to have<br>
> <a href="http://developer.openstack.org/api-ref/image/v2/index.html" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/image/v2/index.<wbr>html</a> for example.<br>
><br>
> What is happening now is the use of a v2-ext directory:<br>
> <a href="http://developer.openstack.org/api-ref/networking/v2-ext/#fwaas-v2-0-current-fw-firewalls-firewall-policies-firewall-rules" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/networking/v2-ext/<wbr>#fwaas-v2-0-current-fw-<wbr>firewalls-firewall-policies-<wbr>firewall-rules</a><br>
<br>
</span>I think the docs publishing process does not support file deletion.<br>
I see several files remaining even though they have been removed.<br></blockquote><div><br></div><div>It does not. You have to file a bug so someone with FTP access can manually delete them until we get docs publishing with AFS. [1] </div><div><br></div><div>I once had the FTP creds for the site but have lost them, I'll have to get them again from Infra. Or, Andreas, if you have a minute, can you do it? </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">
<span class=""><br>
><br>
>><br>
>><br>
>> - what is a good name for main neutron API (provided by 'neutron' repo)?<br>
><br>
><br>
> Armando is suggesting neutron-lib as the doc repo, and Networking API as the<br>
> name, right? Perhaps I misunderstand you. I don't envision changing that<br>
> simply because of movement of source files, do you?<br>
<br>
</span>Yes. Your understanding is correct.<br>
We decided to use neutron-lib as the doc repo and Networking API as the name.<br>
<br>
What I am asking is about page naming 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 am thinking dedicated pages per networking project,<br>
For example, <a href="http://developer.openstack.org/api-ref/networking/service-function-chaining/" rel="noreferrer" target="_blank">http://developer.openstack.<wbr>org/api-ref/networking/<wbr>service-function-chaining/</a><br>
(for networking-sfc)<br></blockquote><div><br></div><div>Sure, that sounds good. Only addition would be the version number as indicated above.</div><div><br></div><div>Thanks for filling in the details as we get more real info!</div><div>Anne</div><div><br></div><div><br></div><div>1. <a href="https://review.openstack.org/#/c/276482/">https://review.openstack.org/#/c/276482/</a> </div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
<span class=""><font color="#888888"><br>
Akihiro<br>
</font></span><div class=""><div class="h5"><br>
><br>
> Anne<br>
><br>
>><br>
>><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,<br>
>> >> as<br>
>> >> far as I can tell. Because of the user experience, I'm making a<br>
>> >> judgement<br>
>> >> call that these cannot be included in the common navigation. I have<br>
>> >> 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<br>
>> >> 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<br>
>> >> 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<br>
>> >> <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<br>
>> >> 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<br>
>> >> comfortable<br>
>> >> with the accuracy of information and build stability. Please help out<br>
>> >> 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<br>
>> >> 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>
>> >><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>
><br>
><br>
><br>
><br>
> --<br>
> Anne Gentle<br>
> <a href="http://www.justwriteclick.com" rel="noreferrer" target="_blank">www.justwriteclick.com</a><br>
</div></div></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>