RST Course

RST

rst or reST means reStructuredText, file with extension .rst. It's a language that is great to write technical documentation for your code, as you may have seen the usual Sphinx+Readthedocs template. You could have seen it in Python too, or on GitHub (ex: README.rst).

We will focus on Readthedocs, a continuous integration system that allows you

  • to write code (you write .rst files by yourself)
  • you link the git where the documentation is hosted with Readthedocs
  • then when changes are made in the documentation, automatically, the website will have the new docs.
  • like git, you can have different branches, so one can switch to a version of the documentation easily

I started using it after seeing a lot of programmers using it, such as


Installing sphinx

Sphinx is creating a website from your documentation. This is what Readthedocs will use. For python comments, you can skip this section.

  • pip install -U sphinx (pip should be installed)
  • sphinx-build --version (check your PATH)
  • I'm using make html to compile in HTML on Windows from the cmd

Sphinx uses a tree-like system, we need to link the pages together. We do that with toctree directive

.. toctree::
 :maxdepth:

    Name printed     <file_rst_without_extension>

Writing RST documents

Here is a list of the most commons directives

As a side note, space and indents are quite important in rst, so be sure to check your indents if the compiler fails somewhere, and you don't know what's the error.


Sources