ReST Builder extension for Sphinx

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.


  • Sphinx 1.0 or later
  • Python 2.6 or later

Installation Procedure

Using pip

To install ReST Builder:

pip install sphinxcontrib-restbuilder


Point releases of sphinxcontrib-restbuilder are available from For manuall installation download it and install it at any place you like. Make sure to adjust sys.path in to tell Sphinx where to look for it. Assuming it is installed in exts/sphinxcontrib:


Development release

To install the (unstable) development code:

hg clone
cd sphinx-contrib/restbuilder
python install

Example Usage

  1. Initialize a documentation directory using sphinx-quickstart if you have not done so. This will will create a file called

  2. Add ReST builder as a extension in

    extensions = ['sphinxcontrib.restbuilder']

    Typically, restbuilder is used in conjunction with autodoc:

    extensions = ['sphinx.ext.autodoc', 'sphinxcontrib.restbuilder']
  3. Optionally configure restbuildier by setting the following variables in 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()
  4. Write the documentation for your project :)

  5. 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
    sphinx-build -b rst path_to/myproject/doc path_to/
    cd path_to/
    git commit -a -m "Update documentation"
    git push origin

Configuration Variables

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 <>