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
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 htmlto 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:: :maxdepth: Name printed <file_rst_without_extension>
Writing RST documents
Here is a list of the most commons directives
- images and links
- math (latex)
- UML (plantuml)
- notes, ...
- class or methods
- side note
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.