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:annegen...@justwriteclick.com] Sent: Sunday, August 21, 2016 8:20 AM To: Shuu Mutou <shu-mu...@rf.jp.nec.com> Cc: m...@redhat.com; Haruhiko Katou <har-ka...@ts.jp.nec.com>; openstack-dev@lists.openstack.org; openstack-d...@lists.openstack.org; kenichi.omi...@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-mu...@rf.jp.nec.com<mailto:shu-mu...@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:annegen...@justwriteclick.com<mailto:annegen...@justwriteclick.com>] > Sent: Wednesday, August 17, 2016 11:55 AM > To: Mutou Shuu(武藤 周) <shu-mu...@rf.jp.nec.com<mailto:shu-mu...@rf.jp.nec.com>> > Cc: > openstack-dev@lists.openstack.org<mailto:openstack-dev@lists.openstack.org>; > m...@redhat.com<mailto:m...@redhat.com>; Katou Haruhiko(加 > 藤 治彦) <har-ka...@ts.jp.nec.com<mailto:har-ka...@ts.jp.nec.com>>; > openstack-d...@lists.openstack.org<mailto:openstack-d...@lists.openstack.org>; > kenichi.omi...@necam.com<mailto:kenichi.omi...@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-mu...@rf.jp.nec.com<mailto:shu-mu...@rf.jp.nec.com> > <mailto:shu-mu...@rf.jp.nec.com<mailto:shu-mu...@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:annegen...@justwriteclick.com<mailto:annegen...@justwriteclick.com> > <mailto:annegen...@justwriteclick.com<mailto:annegen...@justwriteclick.com>> ] > > Sent: Monday, August 15, 2016 11:00 AM > > To: Hongbin Lu <hongbin...@huawei.com<mailto:hongbin...@huawei.com> > <mailto:hongbin...@huawei.com<mailto:hongbin...@huawei.com>> > > > Cc: > openstack-dev@lists.openstack.org<mailto:openstack-dev@lists.openstack.org> > <mailto:openstack-dev@lists.openstack.org<mailto:openstack-dev@lists.openstack.org>> > ; enstack.org<http://enstack.org> > <http://enstack.org> > > > <openstack-d...@lists.openstack.org<mailto:openstack-d...@lists.openstack.org> > <mailto:openstack-d...@lists.openstack.org<mailto:openstack-d...@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...@huawei.com<mailto:hongbin...@huawei.com> > <mailto:hongbin...@huawei.com<mailto:hongbin...@huawei.com>> > > <mailto:hongbin...@huawei.com<mailto:hongbin...@huawei.com> > <mailto:hongbin...@huawei.com<mailto:hongbin...@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:annegen...@justwriteclick.com<mailto:annegen...@justwriteclick.com> > <mailto:annegen...@justwriteclick.com<mailto:annegen...@justwriteclick.com>> > > > <mailto:annegen...@justwriteclick.com<mailto:annegen...@justwriteclick.com> > <mailto:annegen...@justwriteclick.com<mailto:annegen...@justwriteclick.com>> > > ] > > Sent: August-10-16 3:50 PM > > To: OpenStack Development Mailing List; > > > openstack-d...@lists.openstack.org<mailto:openstack-d...@lists.openstack.org> > <mailto:openstack-d...@lists.openstack.org<mailto:openstack-d...@lists.openstack.org>> > > > <mailto:openstack-d...@lists.openstack.org<mailto:openstack-d...@lists.openstack.org> > <mailto:openstack-d...@lists.openstack.org<mailto:openstack-d...@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-d...@lists.openstack.org<mailto:openstack-d...@lists.openstack.org> > <mailto:openstack-d...@lists.openstack.org<mailto:openstack-d...@lists.openstack.org>> > > > <mailto:openstack-d...@lists.openstack.org<mailto:openstack-d...@lists.openstack.org> > <mailto:openstack-d...@lists.openstack.org<mailto:openstack-d...@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-d...@lists.openstack.org<mailto:openstack-d...@lists.openstack.org> > <mailto:openstack-d...@lists.openstack.org<mailto:openstack-d...@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>
__________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: openstack-dev-requ...@lists.openstack.org?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
