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. > Do we place all APIs from stadium projects under 'v2' directory, or > is 'v2' directory unnecessary?
If we avoid the 'v2' directory perhaps we will be better prepared when we adopt micro-versioning? > > - what is a good name for main neutron API (provided by 'neutron' repo)? core? base? neutron? :) > > 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 Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
