What is Sphinx and the RST syntax ?
Sphinx is a tool that ease the creation of documentation for software written in Python. Nevertheless, it can be used for other languages and more general documentation such as this document. Sphinx is widely used within the Python community and there are already many good tutorials and documentation about it. This tutorial was started a while ago when Sphinx project started. I’ve been using sphinx professionally and for my own purpose. Since I’ve taken quite a few notes, I put them together and put it online, hoping it could be of interest for some of you.
In the Starting with Sphinx section, the sub-sections Why Sphinx and for which users ? and QuickStart provide will guide you on starting your own Sphinx project. If you want to see the RST and Sphinx syntax, jump directly to the Restructured Text (reST) and Sphinx CheatSheet section.
Finally, if you are using Sphinx to document a Python project, have a look at the sections Example on how to document your Python docstrings and How to include test in your Python docstrings using doctest.
This tutorial is not covering all Sphinx possibilities and I would strongly recommend anyone willing to use sphinx to look at the sphinx homepage for latests updates and especially the multitude of add-ons (directives) that are added all the time (e.g. LaTeX can be included, plots, ...).