Welcome to an introduction to reStructuredText¶
Indices and tables¶
This is a document written in ReStructuredtext to describe steps to use this documentation tool.
Background¶
The following quote is from: http://docutils.sourceforge.net/rst.html “reStructuredText is an easy-to-read, what-you-see-is-what-you-get plaintext markup syntax and parser system. It is useful for in-line program documentation (such as Python docstrings), for quickly creating simple web pages, and for standalone documents. reStructuredText is designed for extensibility for specific application domains. The reStructuredText parser is a component of Docutils. reStructuredText is a revision and reinterpretation of the StructuredText and Setext lightweight markup systems.”
The primary goal of reStructuredText is to define and implement a markup syntax for use in Python docstrings and other documentation domains, that is readable and simple, yet powerful enough for non-trivial use. The intended purpose of the markup is the conversion of reStructuredText documents into useful structured data formats.
Global View of Steps To Use reStructured Text¶
- Install Python 2.7 or later https://www.python.org/downloads
- Make sure docutils is installed http://docutils.sourceforge.net
- Sphinx* http://www.sphinx-doc.org/en/stable
*My understanding is that docutils can generate documentation without Sphinx. But Sphinx is recommended for increased ease and functionality. I used Sphinx to generate these pages. This text (from the Sphinx link above) describes the relationship of the software: “Sphinx uses reStructuredText as its markup language, and many of its strengths come from the power and straightforwardness of reStructuredText and its parsing and translating suite, the Docutils.”