Open Stack

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.
  Do we place all APIs from stadium projects under 'v2' directory, or
is 'v2' directory unnecessary?

- what is a good name for main neutron API (provided by 'neutron' repo)?

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
>