[openstack-dev] [OpenStack-docs] [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-dev
mailing list