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

Anne Gentle annegentle at justwriteclick.com
Sun Aug 21 01:20:16 UTC 2016


On Fri, Aug 19, 2016 at 2:27 AM, Shuu Mutou <shu-mutou at rf.jp.nec.com> wrote:

> >       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?
>
>
Sure, sounds like there's some info missing that I can clarify.

All HTML built for OpenStack sites are copied via FTP. There's no
difference except for the CSS and JavaScript provided by openstackdocstheme
and built by os-api-ref.

Fairy-slipper is no longer being worked on as a common solution to serving
all OpenStack API information. It was used for migration purposes.

Lars's patch could find a way to use the CSS and JS to create a seamless
experience for end-users.

Anne



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


-- 
Anne Gentle
www.justwriteclick.com
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-dev/attachments/20160820/b7775228/attachment.html>


More information about the OpenStack-dev mailing list