[OpenStack-docs] [openstack-dev] [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-docs/attachments/20160820/b7775228/attachment-0001.html>
More information about the OpenStack-docs
mailing list