Skip to content

A Sphinx builder/writer to output reStructuredText (rst) files

License

Notifications You must be signed in to change notification settings

sphinx-contrib/restbuilder

Repository files navigation

README for reST Builder

Sphinx extension to build reST (reStructuredText) files.

This extension is in particular useful to use in combination with the autodoc extension to automatically generate documentation for use by any rst parser (such as the GitHub wiki).

In itself, the extension is fairly straightforward -- it takes the parsed reST file from Sphinx and outputs it as reST.

Requirements

Sphinx 1.4 - 1.8 and Python 2.7 are partly supported. It does work, but some markup may not parse correctly.

Installing

Using pip

pip install sphinxcontrib-restbuilder

Manual

git clone https://github.com/sphinx-contrib/restbuilder.git
cd restbuilder
python setup.py install

If you want to try reST builder without using the setuptools installer, you can put the reST builder in an extension subdirectory, and adjust sys.path to tell Sphinx where to look for it:

  • Add the extensions directory to the path in conf.py. E.g.:

    sys.path.append(os.path.abspath('exts'))
    

Usage

  • Set the builder as a extension in conf.py:

    extensions = ['sphinxcontrib.restbuilder']
    
  • Run sphinx-build with target rst:

    sphinx-build -b rst -c . build/rst
    

Configuration

The following four configuration variables are defined by sphinxcontrib.restbuilder:

rst_file_suffix
This is the file name suffix for generated reST files. The default is ".rst".
rst_link_suffix
Suffix for generated links to reST files. The default is whatever rst_file_suffix is set to.
rst_file_transform
Function to translate a docname to a filename. By default, returns docname + rst_file_suffix.
rst_link_transform:
Function to translate a docname to a (partial) URI. By default, returns docname + rst_link_suffix.

Further Reading

Feedback

The reST builder is in a preliminary state. It's not (yet) widely used, so any feedback is particularly welcome.