On Fri, Aug 19, 2016 at 2:27 AM, Shuu Mutou <[email protected]> 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:[email protected]] > > Sent: Wednesday, August 17, 2016 11:55 AM > > To: Mutou Shuu(武藤 周) <[email protected]> > > Cc: [email protected]; [email protected]; Katou Haruhiko(加 > > 藤 治彦) <[email protected]>; [email protected]; > > [email protected] > > Subject: Re: [OpenStack-docs] [openstack-dev] [Magnum] Using common > > tooling for API docs > > > > > > > > On Tue, Aug 16, 2016 at 1:05 AM, Shuu Mutou <[email protected] > > <mailto:[email protected]> > 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:[email protected] > > <mailto:[email protected]> ] > > > Sent: Monday, August 15, 2016 11:00 AM > > > To: Hongbin Lu <[email protected] > > <mailto:[email protected]> > > > > Cc: [email protected] > > <mailto:[email protected]> ; enstack.org > > <http://enstack.org> > > > <[email protected] > > <mailto:[email protected]> > > > > 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 < > [email protected] > > <mailto:[email protected]> > > > <mailto:[email protected] <mailto:[email protected]> > > > > 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:[email protected] > > <mailto:[email protected]> > > > <mailto:[email protected] > > <mailto:[email protected]> > ] > > > Sent: August-10-16 3:50 PM > > > To: OpenStack Development Mailing List; > > > [email protected] > > <mailto:[email protected]> > > > <mailto:[email protected] > > <mailto:[email protected]> > > > > 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 > > > [email protected] > > <mailto:[email protected]> > > > <mailto:[email protected] > > <mailto:[email protected]> > > > > > > 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 > > [email protected] > > <mailto:[email protected]> > > 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 Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
