Open Stack

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.

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

>
>>
>>
>> - 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)

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