Open Stack

On Fri, Aug 12, 2016 at 3:29 AM, Akihiro Motoki <amotoki at gmail.com> wrote:

> this mail focuses on neutron-specific topics. I dropped cinder and ironic
> tags.
>
> 2016-08-11 23:52 GMT+09:00 Anne Gentle <annegentle at justwriteclick.com>:
> >
> >
> > On Wed, Aug 10, 2016 at 2:49 PM, Anne Gentle <
> annegentle at justwriteclick.com>
> > 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
> > OpenStack-docs at lists.openstack.org
> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> >
>



-- 
Anne Gentle
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160812/df2a6406/attachment.html>