Sphinx extension to build reST (reStructuredText) files.
This extension is in particular useful to use in combination with the autodoc extension. In this combination, autodoc generates the documentation based on docstrings, and restbuilder outputs the result are reStructuredText (.rst) files. The resulting files can be fed to any reST parser, for example, they can be automatically uploaded to the GitHub wiki of a project.
In itself, the extension is fairly straightforward – it takes the parsed reST file from Sphinx and outputs it as reST.
Point releases of sphinxcontrib-restbuilder are available from https://pypi.python.org/pypi/sphinxcontrib-restbuilder. For manuall installation download it and install it at any place you like. Make sure to adjust sys.path in conf.py to tell Sphinx where to look for it. Assuming it is installed in exts/sphinxcontrib:
sys.path.append(os.path.abspath('exts'))
To install the (unstable) development code:
hg clone http://bitbucket.org/birkenfeld/sphinx-contrib
cd sphinx-contrib/restbuilder
python setup.py install
Initialize a documentation directory using sphinx-quickstart if you have not done so. This will will create a file called conf.py.
Add ReST builder as a extension in conf.py:
extensions = ['sphinxcontrib.restbuilder']
Typically, restbuilder is used in conjunction with autodoc:
extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.restbuilder']
Optionally configure restbuildier by setting the following variables in conf.py. The variables are explained in the next section. For example, the following configuration generates reST files which can be uploaded to a GitHub wiki:
rst_file_suffix = '.rst'
rst_link_suffix = ''
rst_line_width = 78
rst_indent = 4
def rst_file_transform(docname):
if docname == 'index':
docname = 'home'
return docname.title() + rst_file_suffix
def rst_link_transform(docname):
if docname == 'index':
return 'wiki'
return 'wiki/' + docname.title()
Write the documentation for your project :)
Run sphinx-build with target rst:
sphinx-build -b rst . build/rst
The generated rest files are now available in the build/rst directory, ready to be parsed by any rest parser. A typical workflow to upload to a GitHub wiki is:
git clone https://github.com/myusername/myproject.wiki.git
sphinx-build -b rst path_to/myproject/doc path_to/my_project.wiki
cd path_to/my_project.wiki
git commit -a -m "Update documentation"
git push origin
The following six configuration variables are defined by sphinxcontrib.restbuilder:
This is the file name suffix for generated reST files. The default is ".rst".
Suffix for generated links to reST files. The default is whatever rst_file_suffix is set to.
Function to translate a docname to a filename. By default, returns docname + rst_file_suffix.
Function to translate a docname to a (partial) URI. By default, returns docname + rst_link_suffix.
Maximum line width. By default, 78.
Number of spaces in standard indentation. By default, 4.
The ReST builder is in a preliminary state. It’s not (yet) widely used, so any feedback is particularly welcome.
| Author: | Freek Dijkstra <software@macfreek.nl> |
|---|