From 793ed1d5fd964ec44f3da8f44fa40cad7a8fbd5a Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Fri, 13 May 2016 20:51:14 -0400 Subject: [PATCH] Update README Change-Id: I5e6d6b30757c3d74463fb124e43097311c0fef7d --- README.rst | 61 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 52 insertions(+), 9 deletions(-) diff --git a/README.rst b/README.rst index 6d9d69a..e0df429 100644 --- a/README.rst +++ b/README.rst @@ -4,16 +4,59 @@ os-api-ref Sphinx Extensions to support API reference sites in OpenStack -Please feel here a long description which must be at least 3 lines wrapped on -80 cols, so that distribution package maintainers can use it in their packages. -Note that this is a hard requirement. +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. -* Free software: Apache license -* Documentation: http://docs.openstack.org/developer/os-api-ref -* Source: http://git.openstack.org/cgit/openstack/os-api-ref -* Bugs: http://bugs.launchpad.net/replace with the name of the project on launchpad +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 --------- +======== -* TODO +* 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 keystone 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. + +* ``.. litteralinclude`` 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 +* Source: http://git.openstack.org/cgit/openstack/os-api-ref