[OpenStack-docs] [openstack-dev] [Magnum] Using common tooling for API docs

Shuu Mutou shu-mutou at rf.jp.nec.com
Fri Aug 19 07:27:10 UTC 2016


> 	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?
> 
> 
> 
> It does say either/or in the API WG guideline:
> http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html

Yes. Also Ken'ichi Omichi said.


> This isn't about a contest between projects for the best approach. This
> is about serving end-users the best information we can.

Yes. Correct information is the best information. The Accuracy is more important than web experience. When I was a user (and SIer), the document accuracy had not been kept. So we had to read source code at last. And now, as a developer (mainly UI plugins), I don't want maintain overlapped content several times (API source code, API reference, helps in client, helps in WebUI, etc). So I spend efforts to the spec auto-generation.


> I'm reporting what I'm seeing from a broader viewpoint than a single project.
> I don't have a solution other than RST/YAML for common navigation, and I'm
> asking you to provide ideas for that integration point.
> 
> My vision is that even if you choose to publish with OpenAPI, you would
> find a way to make this web experience better. We can do better than this
> scattered approach. I'm asking you to find a way to unify and consider the
> web experience of a consumer of OpenStack services. Can you generate HTML
> that can plug into the openstackdocstheme we are providing as a common tool?

I need to know about the "common tools". Please, let me know what is difference between HTMLs built by Lars's patch and by common tools? Or can fairy-slipper do that from OpenAPI file?


Thanks,
Shu


> -----Original Message-----
> From: Anne Gentle [mailto:annegentle at justwriteclick.com]
> Sent: Wednesday, August 17, 2016 11:55 AM
> To: Mutou Shuu(武藤 周) <shu-mutou at rf.jp.nec.com>
> Cc: openstack-dev at lists.openstack.org; msm at redhat.com; Katou Haruhiko(加
> 藤 治彦) <har-katou at ts.jp.nec.com>; openstack-docs at lists.openstack.org;
> Kenichi.Omichi at necam.com
> Subject: Re: [OpenStack-docs] [openstack-dev] [Magnum] Using common
> tooling for API docs
> 
> 
> 
> On Tue, Aug 16, 2016 at 1:05 AM, Shuu Mutou <shu-mutou at rf.jp.nec.com
> <mailto:shu-mutou at rf.jp.nec.com> > wrote:
> 
> 
> 	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?
> 
> 
> 
> It does say either/or in the API WG guideline:
> http://specs.openstack.org/openstack/api-wg/guidelines/api-docs.html
> 
> 
> 
> 	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.
> 
> 
> 
> 
> This isn't about a contest between projects for the best approach. This
> is about serving end-users the best information we can.
> 
> 
> 	The Best: the references generated from source code.
> 
> 
> 
> I don't want to argue, but anything generated from the source code suffers
> if the source code changes in a way that reviewers don't catch as a
> backwards-incompatible change you can break your contract.
> 
> 
> 	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 think you'll see the evolution of our discussions over the years has
> brought us to this point in time. Yes, there are trade-offs in these
> decisions.
> 
> 
> 
> 	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.
> 
> 
> 
> I ask you to consider the experience of someone consuming the API documents
> OpenStack provides. There are 26 REST API services under an OpenStack
> umbrella. Twelve of them will be included in an unified side-bar navigation
> on developer.openstack.org <http://developer.openstack.org>  due to
> using Sphinx tooling provided as a common web experience. Six of them don't
> have redirects yet from the "old way" to do API reference docs. Seven of
> them are not collected under a single landing page or common sidebar or
> navigation. Three of them have no API docs published to a website.
> 
> I'm reporting what I'm seeing from a broader viewpoint than a single project.
> I don't have a solution other than RST/YAML for common navigation, and I'm
> asking you to provide ideas for that integration point.
> 
> My vision is that even if you choose to publish with OpenAPI, you would
> find a way to make this web experience better. We can do better than this
> scattered approach. I'm asking you to find a way to unify and consider the
> web experience of a consumer of OpenStack services. Can you generate HTML
> that can plug into the openstackdocstheme we are providing as a common tool?
> Thanks,
> Anne
> 
> 
> 
> 	[1] https://review.openstack.org/#/c/303235/
> <https://review.openstack.org/#/c/303235/>
> 	[2] https://github.com/elmiko/pecan-swagger/
> <https://github.com/elmiko/pecan-swagger/>
> 
> 	Regards,
> 	Shu
> 
> 
> 	> -----Original Message-----
> 	> From: Anne Gentle [mailto:annegentle at justwriteclick.com
> <mailto:annegentle at justwriteclick.com> ]
> 	> Sent: Monday, August 15, 2016 11:00 AM
> 	> To: Hongbin Lu <hongbin.lu at huawei.com
> <mailto:hongbin.lu at huawei.com> >
> 	> Cc: openstack-dev at lists.openstack.org
> <mailto:openstack-dev at lists.openstack.org> ; enstack.org
> <http://enstack.org>
> 	> <openstack-docs at lists.openstack.org
> <mailto: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
> <https://review.openstack.org/#/c/329508>  and my comments on
> 	> https://review.openstack.org/#/c/351800/
> <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>
> 	> <mailto: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/>
> 	> <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>
> 	> <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>
> 	> <mailto: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>
> <http://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/>
> 	> <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
> <http://lists.openstack.org/pipermail/openstack-dev/2016-August/101112
> > .
> 	> html
> 	>
> <http://lists.openstack.org/pipermail/openstack-dev/2016-August/101112
> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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/>
> 	> <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>
> 
> 	> <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/>
> 	> <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>
> 	> <http://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>
> <http://www.justwriteclick.com>
> 	>
> 	>
> 	>       _______________________________________________
> 	>       OpenStack-docs mailing list
> 	>       OpenStack-docs at lists.openstack.org
> <mailto:OpenStack-docs at lists.openstack.org>
> 	> <mailto:OpenStack-docs at lists.openstack.org
> <mailto:OpenStack-docs at lists.openstack.org> >
> 	>
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-
> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack->
> 	> docs
> 	>
> <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>
> <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>



More information about the OpenStack-docs mailing list