Part of the cross project session track - https://etherpad.openstack.org/p/newton-api-docs-rst
The first half of the session was spent going over the background issues and the work so far. The TL;DR * We need to get off WADL, it's a dead spec, and it's use is inhibiting contributions * We *need* to get up to date docs to our users, ASAP. The API References are way out of data and inaccurate in most places (and missing entirely for 50% of our projects with REST APIs) * Swagger (OpenAPI) was looked at, but there are hard problems in our legacy APIs that aren't possible to solve within the spec at hand * Nova team started building some semistructured tooling based on RST / Sphinx to move forward. We then looked at the sphinx extension work in the Nova api-ref tree. Question: why not https://pythonhosted.org/sphinxcontrib-httpdomain/? Answer: we have some specific needs on formating, headers where it doesn't fit (see etherpad for full answer). Next Steps: * Nova team is doing a doc sprint to try to get through verification of the content we've got * Once that is done (under control) sdague to work on splitting out sphinx extension into a dedicated project to make it easy for others to consume / contribute * Cinder, Ironic, and Keystone ready to get started on similar conversion -- Sean Dague http://dague.net __________________________________________________________________________ OpenStack Development Mailing List (not for usage questions) Unsubscribe: [email protected]?subject:unsubscribe http://lists.openstack.org/cgi-bin/mailman/listinfo/openstack-dev
