# Sphinx reStructuredText 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 2.0 or later

- Python 3.6 or later

## Installing

### Using pip

> pip install sphinx-rst-builder

### Manual

> git clone https://github.com/davidfritzsche/sphinx-rst-builder.git cd sphinx-rst-builder python setup.py install

If you want to take a look and have a try, 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 = [‘sphinx_rst_builder’]

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

rst_preserve_code_block_flags

  Preserve (some) `.. code-block::` flags if True. Default is False.

## Further Reading

- Sphinx

- reStructuredText

## Feedback

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