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

hieulq at vn.fujitsu.com hieulq at vn.fujitsu.com
Mon Aug 29 08:22:12 UTC 2016


Hi,

The works in Magnum api-ref can be reviewed at [1]. Please take a look and get these to be merged ASAP.

[1]. https://blueprints.launchpad.net/magnum/+spec/magnum-doc-rest-api

Thanks,
Hieu LE.

From: Anne Gentle [mailto:annegentle at justwriteclick.com]
Sent: Sunday, August 21, 2016 8:20 AM
To: Shuu Mutou <shu-mutou at rf.jp.nec.com>
Cc: msm at redhat.com; Haruhiko Katou <har-katou at ts.jp.nec.com>; openstack-dev at lists.openstack.org; openstack-docs at lists.openstack.org; Kenichi.Omichi at necam.com
Subject: Re: [openstack-dev] [OpenStack-docs] [Magnum] Using common tooling for API docs



On Fri, Aug 19, 2016 at 2:27 AM, Shuu Mutou <shu-mutou at rf.jp.nec.com<mailto: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<mailto:annegentle at justwriteclick.com>]
> Sent: Wednesday, August 17, 2016 11:55 AM
> To: Mutou Shuu(武藤 周) <shu-mutou at rf.jp.nec.com<mailto:shu-mutou at rf.jp.nec.com>>
> Cc: openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>; msm at redhat.com<mailto:msm at redhat.com>; Katou Haruhiko(加
> 藤 治彦) <har-katou at ts.jp.nec.com<mailto:har-katou at ts.jp.nec.com>>; openstack-docs at lists.openstack.org<mailto:openstack-docs at lists.openstack.org>;
> Kenichi.Omichi at necam.com<mailto: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>
> <mailto: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> <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>
> <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>
> <mailto: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>
> <mailto:openstack-dev at lists.openstack.org<mailto:openstack-dev at lists.openstack.org>> ; enstack.org<http://enstack.org>
> <http://enstack.org>
>       > <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: 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>>
>       > <mailto: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>>
>       > <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>>
>       > <mailto: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 <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
> <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>
> <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>>
>       > <mailto: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>
> <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-
> docs
> <http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs>
>
>
>
>
>
> --
>
> Anne Gentle
> www.justwriteclick.com<http://www.justwriteclick.com> <http://www.justwriteclick.com>



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


More information about the OpenStack-dev mailing list