Skip to main content
Join the official 2019 Python Developers SurveyStart the survey!

Sphinx reStructuredText builder

Project description

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.

Usage

  • Set the builder as a extension in conf.py:
  • Run sphinx-build with target 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.

Changelog

sphinx-rst-builder 0.0.1 (21 June 2019)

restbuilder 0.2 (7 June 2018)

  • Code moved to https://gitub.com/sphinx-contrib/restbuilder
  • Python 3 compatible (Nicola Musatti)
  • Adhere to rst_indent-specified indentation (Matthew Planchard)
  • Fixed issue where links were converted to plaintext (Matthew Planchard)

restbuilder 0.1 (25 August 2013)

restbuilder (no version) (28 April 2012)

BSD-2-Clause License

Copyright (c) 2019 by David Fritzsche and contributors.

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

  • Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
  • Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Contributors

Freek Dijkstra (macfreek) G. Nicholas d’Andrea (gnidan) Jeffrey Lo (jeffrey_lo) Matthew Planchard (mplanchard) Nicola Musatti (nmusatti) David Fritzsche (davidfritzsche)

Project details


Release history Release notifications

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for sphinx-rst-builder, version 0.0.1
Filename, size File type Python version Upload date Hashes
Filename, size sphinx_rst_builder-0.0.1-py3-none-any.whl (12.3 kB) File type Wheel Python version py3 Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page