Tips and tricks if you are in a hurry

If something doesn’t work and spans several lines try if it works by adding a new emty line between it.

Lists / bulletpoints / numerations are messed up

Conside that each new indentation levels needs of a newline before its first element, and after its last element. The first line is counter-intuitive.

To automatically enumerate use the # symbol.

Cross-referencing between different rts files

This is a very powerful feature that you should use. But don’t bother looking up how to do it, there are some incompatibilities and the base documentation is not clear enough. Just do the following:

  • In the document that you want to target add a line with:
    • .. _My-Multi-Word-Unique-String:
  • In the document that is the source to this link add:
    • :ref:`My-Multi-Word-Unique-String`

Embedding Html

If you want to directly embed another html within the rst page (which is built as an html), use the following two lines:

  1. .. raw:: html
  2. :file: filename.html

Note that filename.html is in the same folder as the current rst. Subfolders should be possible. The lines must be together, otherwise the raw is not applied to the file command.

Glossary

Create with glossary directive and then add each entry like in a indented list.

Reference via :term:`term-name` or :term:`display-text<term-name>.

As well as :term:`term-name`, other terms are also relevant.

.. glossary::

  term-name
    Some descritpion

http://sublime-and-sphinx-guide.readthedocs.io/en/latest/glossary.html