On Thu, Aug 18, 2016 at 3:33 AM, Akihiro Motoki <[email protected]> wrote:
> 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. > Ah, okay, right. Would developer.openstack.org/api-ref/networking/lbaas/v1 and developer.openstack.org/api-ref/networking/lbaas/v2 work? > > >> > >> 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. > 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] 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? > > > > >> > >> > >> - 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) > Sure, that sounds good. Only addition would be the version number as indicated above. Thanks for filling in the details as we get more real info! Anne 1. https://review.openstack.org/#/c/276482/ > > 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 > -- 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
