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