Sphinx extension to support OpenStack API reference pages creation
Go to file
Sean Dague f93c467e9a add experimental microversion selector
This adds experimental support for a microversion selector. The
interface for this may well change over time. To currently use this we
need 2 values in the sphinx conf.py to specify min and max
microversions. If you don't have those added, nothing is changed in
the UI.

Use at your own risk. However it's much easier to get feedback if we
have this in the package.

Change-Id: Iaf7e117ea5792bb3b60c1fd0ae416b241ab89d65
2016-06-03 06:46:23 -04:00
doc/source Added more details to usage.rst 2016-06-01 14:51:23 -04:00
os_api_ref add experimental microversion selector 2016-06-03 06:46:23 -04:00
.coveragerc Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
.gitignore Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
.gitreview Added .gitreview 2016-05-13 21:14:19 +00:00
.mailmap Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
.testr.conf Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
CONTRIBUTING.rst fix docs to link the new bug tracker 2016-05-17 19:37:41 +00:00
HACKING.rst Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
LICENSE Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
MANIFEST.in Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
README.rst Trivial: fix typos in README.rst 2016-05-19 19:57:37 -04:00
TESTS.rst add a list of tests we should have 2016-05-27 16:04:12 -04:00
babel.cfg Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
requirements.txt add first basic unit test 2016-05-26 06:31:51 -04:00
setup.cfg Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
setup.py Initial Cookiecutter Commit. 2016-05-13 19:54:08 -04:00
test-requirements.txt add first basic unit test 2016-05-26 06:31:51 -04:00
tox.ini make testing be non parallel 2016-05-27 16:04:12 -04:00

README.rst

os-api-ref

Sphinx Extensions to support API reference sites in OpenStack

This project is a collection of sphinx stanzas that assist in building an API Reference site for an OpenStack project in RST. RST is great for unstructured English, but displaying semi structured (and repetitive) data in tables is not it's strength. This provides tooling to insert semi-structured data describing request and response parameters, and turn those into nice tables.

The project also includes a set of styling (and javascript) that is expected to layer on top of an oslosphinx theme base. This provides a nice set of collapsing sections for REST methods and javascript controls to expand / collapse all sections.

Features

  • 2 new sphinx stanzas rest_method and rest_parameters which support putting semi-structured data into the RST files.

TODO

A list, in no particular order, of things we should do in this project. If you would like to contribute to any of these please show up in #openstack-dev on IRC and ask for sdague to discuss.

  • Enhance documentation with examples and best practices
  • Testing for the code
  • max_microversion parameter support - so that we automatically tag parameters that have been removed
  • microversion selector, so that you can get a version of the api-ref that hides all microversion elements beyond your selected version (this one is going to be a bit of complex javascript)
  • make this compatible with openstackdocstheme (which is equal parts work here and with the openstack docs theme).

Potential ideas

These aren't even quite todos, but just ideas about things that might be useful.

  • .. literalinclude is good for API samples files to be included, but should we have more markup that includes the full REST /URL as well

Sphinx stanzas

TODO: document the details of the stanzas