further enhance documentation
Change-Id: I13b9f634529d4e2edd2cc75bdc528b5cebb6a1a2
This commit is contained in:
11
README.rst
11
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
|
||||
|
||||
|
@@ -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
|
||||
|
@@ -1,4 +1,4 @@
|
||||
============
|
||||
|
||||
Contributing
|
||||
============
|
||||
.. include:: ../../CONTRIBUTING.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`
|
||||
|
||||
|
@@ -1,4 +1,3 @@
|
||||
============
|
||||
Installation
|
||||
============
|
||||
|
||||
|
@@ -1,4 +1,3 @@
|
||||
========
|
||||
Usage
|
||||
========
|
||||
|
||||
|
@@ -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'}
|
||||
|
Reference in New Issue
Block a user