Open Stack

Hi Anne,

AFAIK, the API WG adopted Swagger (OpenAPI) as common tool for API docs.
Anne, has not the adoption been changed? Otherwise, do we need to maintain much RST files also?

IMO, for that the reference and the source code doesn't have conflict, these should be near each other as possible as follow. And it decreases maintainance costs for documents, and increases document reliability. So I believe our approach is more ideal.

The Best: the references generated from source code.
Better: the references written in docstring.

We know some projects abandoned these approach, and then they uses RST + YAML. 
But we hope decreasing maintainance cost for the documents. So we should not create so much RST files, I think.


I'm proceeding auto-generation of swagger spec from magnum source code using pecan-swagger [1], and improving pecan-swagger with Michael McCune [2].
These will generate almost Magnum API specs automatically in OpenAPI format.
Also, these approach can be adopted by other APIs that uses pecan and WSME.
Please check this also.

[1] https://review.openstack.org/#/c/303235/
[2] https://github.com/elmiko/pecan-swagger/

Regards,
Shu


> -----Original Message-----
> From: Anne Gentle [mailto:annegentle at justwriteclick.com]
> Sent: Monday, August 15, 2016 11:00 AM
> To: Hongbin Lu <hongbin.lu at huawei.com>
> Cc: openstack-dev at lists.openstack.org; enstack.org
> <openstack-docs at lists.openstack.org>
> Subject: Re: [openstack-dev] [OpenStack-docs] [Magnum] Using common
> tooling for API docs
> 
> Hi Hongbin,
> 
> Thanks for asking. I'd like for teams to look for ways to innovate and
> integrate with the navigation as a good entry point for OpenAPI to become
> a standard for OpenStack to use. That said, we have to move forward and
> make progress.
> 
> Is Lars or anyone on the Magnum team interested in the web development work
> to integrate with the sidebar? See the work at
> https://review.openstack.org/#/c/329508 and my comments on
> https://review.openstack.org/#/c/351800/ saying that I would like teams
> to integrate first to provide the best web experience for people consuming
> the docs.
> 
> Anne
> 
> On Fri, Aug 12, 2016 at 4:43 PM, Hongbin Lu <hongbin.lu at huawei.com
> <mailto:hongbin.lu at huawei.com> > wrote:
> 
> 
> 	Hi team,
> 
> 
> 
> 	As mentioned in the email below, Magnum are not using common tooling
> for generating API docs, so we are excluded from the common navigation of
> OpenStack API. I think we need to prioritize the work to fix it. BTW, I
> notice there is a WIP patch [1] for generating API docs by using Swagger.
> However, I am not sure if Swagger belongs to “common tooling” (docs team,
> please confirm).
> 
> 
> 
> 	[1] https://review.openstack.org/#/c/317368/
> <https://review.openstack.org/#/c/317368/>
> 
> 
> 
> 	Best regards,
> 
> 	Hongbin
> 
> 
> 
> 	From: Anne Gentle [mailto:annegentle at justwriteclick.com
> <mailto:annegentle at justwriteclick.com> ]
> 	Sent: August-10-16 3:50 PM
> 	To: OpenStack Development Mailing List;
> openstack-docs at lists.openstack.org
> <mailto:openstack-docs at lists.openstack.org>
> 	Subject: [openstack-dev] [api] [doc] API status report
> 
> 
> 
> 	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 <http://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/
> <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
> <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/
> <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/
> <http://developer.openstack.org/api-ref/dns/>
> 
> 	glance http://developer.openstack.org/api-ref/image/
> <http://developer.openstack.org/api-ref/image/>
> 	heat http://developer.openstack.org/api-ref/orchestration/
> <http://developer.openstack.org/api-ref/orchestration/>
> 	ironic http://developer.openstack.org/api-ref/baremetal/
> <http://developer.openstack.org/api-ref/baremetal/>
> 	keystone http://developer.openstack.org/api-ref/identity/
> <http://developer.openstack.org/api-ref/identity/>
> 	manila
> http://developer.openstack.org/api-ref/shared-file-systems/
> <http://developer.openstack.org/api-ref/shared-file-systems/>
> 	neutron-lib http://developer.openstack.org/api-ref/networking/
> <http://developer.openstack.org/api-ref/networking/>
> 	nova http://developer.openstack.org/api-ref/compute/
> <http://developer.openstack.org/api-ref/compute/>
> 	sahara http://developer.openstack.org/api-ref/data-processing/
> <http://developer.openstack.org/api-ref/data-processing/>
> 	senlin http://developer.openstack.org/api-ref/clustering/
> <http://developer.openstack.org/api-ref/clustering/>
> 	swift http://developer.openstack.org/api-ref/object-storage/
> <http://developer.openstack.org/api-ref/object-storage/>
> 	zaqar http://developer.openstack.org/api-ref/messaging/
> <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
> 
> 
> 
> 	--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
> <http://docs.openstack.org/contributor-guide/api-guides.html> .
> 
> 
> 
> 	For searchlight, looking at
> http://developer.openstack.org/api-ref/search/
> <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
> <http://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 <http://www.justwriteclick.com>
> 
> 
> 	_______________________________________________
> 	OpenStack-docs mailing list
> 	OpenStack-docs at lists.openstack.org
> <mailto:OpenStack-docs at lists.openstack.org>
> 	http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-
> docs
> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>
> 
> 
> 
> 
> 
> 
> --
> 
> Anne Gentle
> www.justwriteclick.com <http://www.justwriteclick.com>