Open Stack

On Thu, Aug 18, 2016 at 3:33 AM, Akihiro Motoki <amotoki at gmail.com> wrote:

> 2016-08-13 7:36 GMT+09:00 Anne Gentle <annegentle at justwriteclick.com>:
> >
> >
> > 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.
>
> 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
> >> > OpenStack-docs at lists.openstack.org
> >> > http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
> >> >
> >
> >
> >
> >
> > --
> > Anne Gentle
> > www.justwriteclick.com
>



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