From dec31938d06a88c7e7252f49ccb091a0139ea5be Mon Sep 17 00:00:00 2001 From: Sean Dague Date: Sat, 14 May 2016 08:55:41 -0400 Subject: [PATCH] further enhance documentation Change-Id: I13b9f634529d4e2edd2cc75bdc528b5cebb6a1a2 --- README.rst | 11 +++++---- doc/source/conf.py | 2 +- doc/source/contributing.rst | 2 +- doc/source/index.rst | 14 ++++-------- doc/source/installation.rst | 1 - doc/source/usage.rst | 1 - os_api_ref/__init__.py | 45 +++++++++++++++++++++++++++++-------- 7 files changed, 47 insertions(+), 29 deletions(-) diff --git a/README.rst b/README.rst index e0df429..c9e2601 100644 --- a/README.rst +++ b/README.rst @@ -1,6 +1,5 @@ -=============================== os-api-ref -=============================== +========== Sphinx Extensions to support API reference sites in OpenStack @@ -17,13 +16,13 @@ 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 @@ -41,7 +40,7 @@ discuss. 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. @@ -52,7 +51,7 @@ be useful. Sphinx stanzas -============== +-------------- TODO: document the details of the stanzas diff --git a/doc/source/conf.py b/doc/source/conf.py index d37d785..a562440 100755 --- a/doc/source/conf.py +++ b/doc/source/conf.py @@ -38,7 +38,7 @@ master_doc = 'index' # General information about the project. project = u'os-api-ref' -copyright = u'2013, OpenStack Foundation' +copyright = u'2016, The contributors' # If true, '()' will be appended to :func: etc. cross-reference text. add_function_parentheses = True diff --git a/doc/source/contributing.rst b/doc/source/contributing.rst index 1728a61..0021f68 100644 --- a/doc/source/contributing.rst +++ b/doc/source/contributing.rst @@ -1,4 +1,4 @@ -============ + Contributing ============ .. include:: ../../CONTRIBUTING.rst diff --git a/doc/source/index.rst b/doc/source/index.rst index ae441f6..b2b8c79 100644 --- a/doc/source/index.rst +++ b/doc/source/index.rst @@ -6,15 +6,10 @@ Welcome to os-api-ref's documentation! ======================================================== -Contents: - -.. toctree:: - :maxdepth: 2 - - readme - installation - usage - contributing +.. include:: readme.rst +.. include:: installation.rst +.. include:: usage.rst +.. include:: contributing.rst Indices and tables ================== @@ -22,4 +17,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - diff --git a/doc/source/installation.rst b/doc/source/installation.rst index 8b97634..967a6b0 100644 --- a/doc/source/installation.rst +++ b/doc/source/installation.rst @@ -1,4 +1,3 @@ -============ Installation ============ diff --git a/doc/source/usage.rst b/doc/source/usage.rst index ac8eb33..051d007 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -1,4 +1,3 @@ -======== Usage ======== diff --git a/os_api_ref/__init__.py b/os_api_ref/__init__.py index a739cbb..000973d 100644 --- a/os_api_ref/__init__.py +++ b/os_api_ref/__init__.py @@ -80,27 +80,40 @@ def ordered_load(stream, Loader=yaml.Loader, object_pairs_hook=OrderedDict): return yaml.load(stream, OrderedLoader) -def full_name(cls): - return cls.__module__ + '.' + cls.__name__ - - class rest_method(nodes.Part, nodes.Element): - """rest_method custom node type + """Node for rest_method stanza - We specify a custom node type for rest_method so that we can - accumulate all the data about the rest method, but not render as - part of the normal rendering process. This means that we need a - renderer for every format we wish to support with this. + Because we need to insert very specific HTML at the final stage of + processing, the rest_method stanza needs a custom node type. This + lets us accumulate the relevant data into this node, during + parsing, but not turn it into known sphinx types (lists, tables, + sections). + Then, during the final build phase we transform directly to the + html that we want. + + NOTE: this means we error trying to build latex or man pages for + these stanza types right now. This is all fixable if we add an + output formatter for this node type, but it's not yet a + priority. Contributions welcomed. """ pass class rest_expand_all(nodes.Part, nodes.Element): + """A node placeholder for the expand all button. + + This is a node that we can insert into the doctree which on final + render can be converted to the custom HTML we need for the expand + all button. It is automatically inserted at the top of the page + for API ref documents. + """ pass class RestExpandAllDirective(Directive): + # This tells sphinx that the directive will need to generate + # content during the final build phase. has_content = True def run(self): @@ -464,15 +477,29 @@ def add_assets(app): def setup(app): + # TODO(sdague): if someone wants to support latex/pdf, or man page + # generation using these stanzas, here is where you'd need to + # specify content specific renderers. app.add_node(rest_method, html=(rest_method_html, None)) app.add_node(rest_expand_all, html=(rest_expand_all_html, None)) + + # This specifies all our directives that we're adding app.add_directive('rest_parameters', RestParametersDirective) app.add_directive('rest_method', RestMethodDirective) app.add_directive('rest_expand_all', RestExpandAllDirective) + + # The doctree-read hook is used do the slightly crazy doc + # transformation that we do to get the rest_method document + # structure. app.connect('doctree-read', resolve_rest_references) + + # Add all the static assets to our build during the early stage of building app.connect('builder-inited', add_assets) + + # This copies all the assets (css, js, fonts) over to the build + # _static directory during final build. app.connect('build-finished', copy_assets) return {'version': '0.1'}