Skip to main content

Sphinx Extensions to support API reference sites in OpenStack

Project description

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 openstackdocstheme 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

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for os-api-ref, version 1.0.0
Filename, size File type Python version Upload date Hashes
Filename, size os_api_ref-1.0.0-py2-none-any.whl (78.3 kB) File type Wheel Python version py2 Upload date Hashes View
Filename, size os-api-ref-1.0.0.tar.gz (81.7 kB) File type Source Python version None Upload date Hashes View

Supported by

Pingdom Pingdom Monitoring Google Google Object Storage and Download Analytics Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN DigiCert DigiCert EV certificate StatusPage StatusPage Status page