Read The Docs

Installation

Windows

The following commands should be installed using Windows command prompt with administrative privileges:

> pip install --upgrade pip
> mkvirtualenv rtd
(rtd) > pip install sphinx_rtd_theme

Linux

The following commands are used on a Debian environment:

$ sudo apt install -y python3-virtualenv
$ mkdir ~/p3venv
$ cd ~/p3venv
$ virtualenv rtd
$ source ~/p3venv/rtd/bin/active
(rtd) $ python3 -m pip install --upgrade pip
(rtd) $ pip install sphinx_rtd_theme
(rtd) $ deactivate

Creating a new project

> mkdir docs to create the documentation directory.
> cd docs to go into the documentation directory.
> sphinx-quickstart to create the project.

Build in vim

The macro commands usually assigned to @b are:

Windows

:w to save the current buffer.
!workon rtd && cd .. && make html to go up one directory and call the make.bat or make file to build the html files.

Linux

:w to save the current buffer.
:!cd .. && source ~/p3venv/rtd/bin/activate && make html to go up one directory and call the make.bat or make file to build the html files.
:mks! ~/rtd-session.vim

Full sphinx rebuild

Once in a while, a full rebuild of the project is required because Sphinx only builds for files that have been updated. The easiest approach for this is to touch all .rst files and do a build again in the following manner.

find . -type f -name "*.rst" -exec touch {} +

Once can also issue the command :!cd ..\ && del /s /q build from within VIM if you are using that editor.

Heading Levels

Use the following symbols to create headings:

# with overline
* with overline
=
-
^
"

Useful Modifiers

External URLs: `Label <https://blah.blah.com>`_
.. _DestinationTag: goes in the destination location before a heading, while :ref:`DestinationTag`. provides a link to this destination reference.
Superscript and subscripts directives can be used in this manner. E.g., (价格 jia⁴ ge₂) is jia\ :sup:`4` ge\ :sub:`2`
Maths directives can be done in this way:
- The area of the circle is $A(c) = \pi r^2$ with :math:`A(c) = \pi r^2`. See Math Directive
- :math:`Quoted Spread = \frac{ask - bid}{midpoint}` $Quoted Spread = \frac{ask - bid}{midpoint}$
Figures with captions can be done with .. figure:: diagram.png, indented :align: center on the next line, a blank line, followed by the caption on an indented line.
Use | at the beginning of a line for line blocks where you can ensure each sentence that starts with a line break renders in a separate line without having unnecessary additional line breaks in between.
Use .. admonition:: Heading for text box, a blank line followed by indented lines of text for the words that go into the box.