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
Free software: Apache license
Documentation: http://docs.openstack.org/developer/os-api-ref
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
File details
Details for the file os-api-ref-1.0.0.tar.gz.
File metadata
- Download URL: os-api-ref-1.0.0.tar.gz
- Upload date:
- Size: 81.7 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 2f1bbb6de0a426cbdb12c0dea07f7bb7cf1be28713a62ff68649688220313cd0 |
|
| MD5 | 2395fd4c2493a81ad2c178869525621a |
|
| BLAKE2b-256 | e74d14e73da3e76c8e2198db9b58e4055f99115d3b049d4edf80a8994d0f973a |
Provenance
File details
Details for the file os_api_ref-1.0.0-py2-none-any.whl.
File metadata
- Download URL: os_api_ref-1.0.0-py2-none-any.whl
- Upload date:
- Size: 78.3 kB
- Tags: Python 2
- Uploaded using Trusted Publishing? No
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 148dd68f6355b2977da6a69808a0af6df15a7b01d1c282b2a36bf7f33eaa6548 |
|
| MD5 | 9577d4b284e3bfc9cfe7bc059db6374f |
|
| BLAKE2b-256 | 8e5787f95d85740c2679747abe2351dc28f8238e03b36da4345424ff25d9b760 |
