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. > 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 > > - 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? 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
