Common operations
Virtual environment activation
To activate the virtual environment
usr1@server:~/sphinx$ source .venv/bin/activate
The prompt should look like this
(.venv) usr1@server:~/sphinx$
Virtual environment deactivation
To deactivate virutal environment execute the following
(.venv) usr1@server:~/sphinx$ deactivate
The prompt that is displayed should now look like this
usr1@server:~/sphinx$
Build project (generate html files)
To generate html files from source *.rst files execute the following
(.venv) usr1@server:~/sphinx$ sphinx-build -M html docs/source/ docs/build/
Deploy project (copy html files on web server)
The prompt that is displayed should now look like this
(.venv) usr1@server:~/sphinx$ cp -R -v docs/build/html /var/www/{website directory}/
Useful rst notations
Reference Links :
Sphinx doc : https://www.sphinx-doc.org
Cheat sheets : https://bashtage.github.io/sphinx-material/rst-cheatsheet
reStructuredText Directives : https://docutils.sourceforge.io/docs/ref/rst
Syntax for parts, chapters, sections, etc…
LEVEL 1 : # for parts with overline.
The notation is the following :
########################
Your text here
########################
The resulting look-and-feel is the following :
This is a part
LEVEL 2 : = for sections
The notation is the following :
====================
Your text here
====================
The resulting look-and-feel is the following :
This is a section
LEVEL 3 : - for subsections
The notation is the following :
Your text here
------------------------
The resulting look-and-feel is the following :
This is a subsection
LEVEL 4 : ^ for subsubsections
The notation is the following :
Your text here
^^^^^^^^^^^^^^^^^^^^^^^^^^
The resulting look-and-feel is the following :
This is a subsubsection
LEVEL 5 : asterix for chapters with overline
The notation is the following :
********************
Your text here
********************
The resulting look-and-feel is the following :
This is a chapter
LEVEL 6 : “ for paragraphs
The notation is the following :
Your text here
""""""""""""""""""""""
The resulting look-and-feel is the following :
This is a paragraph
Syntax for horizontal break
Horizontal break : multiple -
Syntax to use tables :
Heading row 1, column 1 |
Heading row 1, column 2 |
Heading row 1, column 3 |
|---|---|---|
Row 1, column 1 |
Row 1, column 3 |
|
Row 2, column 1 |
Row 2, column 2 |
Row 2, column 3 |
Highlighting text
Standard text formatting
emphasis : emphasis
strong – equivalent of strong
literal – equivalent of literal
admonition
Note
This is a tests of how admonition is styled It contains multiple lines Like this
General note
Note
This is note text. Use a note for information you want the user to pay particular attention to.
If note text runs over a line, make sure the lines wrap and are indented to the same level as the note tag. If formatting is incorrect, part of the note might not render in the HTML output.
Notes can have more than one paragraph. Successive paragraphs must indent to the same level as the rest of the note.
Warning
Warning
This is warning text. Use a warning for information the user must understand to avoid negative consequences.
Warnings are formatted in the same way as notes. In the same way, lines must be broken and indented under the warning tag.
attention
Attention
This is a tests of how attention is styled
caution
Caution
This is a tests of how caution is styled
danger
Danger
This is a tests of how danger is styled
hint
Hint
This is a tests of how hint is styled
important
Important
This is a tests of how important is styled
tip
Tip
This is a tests of how important is styled