[OpenStack-docs] [openstack-dev] [Magnum] Using common tooling for API docs
Scott Adkins
adkinss at gmail.com
Sun Aug 21 18:07:50 UTC 2016
On Aug 20, 2016 9:53 PM, "Anne Gentle" <annegentle at justwriteclick.com>
wrote:
>
>
> 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
>
> _______________________________________________
> OpenStack-docs mailing list
> OpenStack-docs at lists.openstack.org
> http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-docs
>
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.openstack.org/pipermail/openstack-docs/attachments/20160821/da8e0395/attachment-0001.html>
More information about the OpenStack-docs
mailing list