Before starting

General view

Sphinx is a tool to create documentation. Although it was originally created for Python, it supports other languages as well.

Sphinx uses reStructuredText as markup language. reST files have the .rst extension. This language is simple. It basically contains 2 types of structures:

1. Inline markup:

   e.g. using ``*`` for *emphasis*
   

2. Explicit construct (roles and directives): Used to construct complex structures like admonitions. E.g.:

   .. note:: A note
   

   is displayed as:

   Note

   A note

The reST markup specification contains all the reST syntax. The reST markup is defined in the docutils project. This project includes also a text processor. You can try it online on http://rst.ninjs.org/ . However, this project is only for single documents.

Sphinx compiles and links all the .rst files to generate the documentation in different formats: html, pdf, epub… However, Sphinx is not only a tool to process the .rst files but also adds new directives and interpreted text roles. One of the most important directives added by Sphinx is the toctree because it allows the interconnection of different documents.

Alternatives

Sphinx and reST have alternatives when it comes to write technical documentation. For example, Asciidoctor uses the asciidoc syntax to create HTML and other formats. Doxygen is also another useful tool to create technical documentation.

Markdown in a popular markup language (as reST) which is specially designed for HTML outputs. It can be used with MkDocs, and optionally Doxygen and even Sphinx.

When it comes to choose between reST and markdown, reST seems to be a better choice according to: http://www.zverovich.net/2016/06/16/rst-vs-markdown.html , https://eli.thegreenplace.net/2017/restructuredtext-vs-markdown-for-technical-documentation/ and http://ericholscher.com/blog/2016/mar/15/dont-use-markdown-for-technical-docs/

Markdown is designed for the web and you can write HTML if the markup syntax is not enough. Said that, it also has some issues. The main one is probably the lack of a standard. There are many different “flavours” incompatible between them. The common mark specication is there to solve this problem, but is still not widely used. Moreover, the invisible markup might not be a good idea; e.g.: When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return.

On the other hand reST is more standardized and uniform and it has built-in support for extensions (and it is written in Python). However, reST is not free of issues. A notable one is that nested markup is not supported (yet).

Note

If you need to switch your documents from one markup to another you can use pandoc

Placing documentation in the project

The suggested place to put the documentation is in a separate folder named doc or docs just below the project main folder.

The structure of a Python project is open and depends on the developers. One of the recommended ways is as follows:

project/
|
|-- project/
|   |-- package/
|   |   |-- __init__.py
|   |   |-- module.py
|   |
|   |-- __init__.py
|   |-- main.py
|
|-- README.rst
|-- setup.py

Note

If your project has more modules and packages, put them under the project directory.

When adding documentation, the structure of the project will end up in something similar to:

project/
|
|-- docs/
|   |-- build/
|   |-- source/
|   |   |-- _templates
|   |   |-- _static
|   |   |-- pkg/
|   |   |-- index.rst
|   |   |-- conf.py
|   |-- Makefile
|
|-- project/
|   |-- package\
|   |   |-- __init__.py
|   |   |-- module.py
|   |
|   |-- __init__.py
|   |-- main.py
|
|-- README.rst
|-- setup.py