The document outlines a workflow for documenting with Sphinx using reStructuredText (RST) to create HTML, detailing the formatting options and basic syntax of RST. It highlights the importance of using plain-text editors for authoring, the use of Sphinx for conversion, and provides resources for setting up a Python virtual environment and installing necessary packages. Additional best practices for source control with Git are also discussed, along with links to relevant documentation and tools.

1. Documenting with Sphinx
ReStructured Text to HTML

2. Authoring
Workflow
Write RST using any 'text' editor
Compile RST to HTML using
Sphinx
Host HTML using any web server

3. ReStructured
Text
• A plain text format
• Also known as RST
• Authored using plain-text editors
• Markdown is used for formatting
• Compiles into HTML
• Intro to simple formatting options at
https://en.wikipedia.org/wiki/ReStructuredText#Ex
amples_of_reST_markup

4. Basic Formatting
First Heading
=============
Sub-heading
-----------
Third Heading
~~~~~~~~~~~~~
Paragraphs are separated
by a blank line.
Two spaces at the end of
a line produces a line
break.
*text* for emphasis
(italics)
**text** for strong
emphasis (boldface)
``text`` for code
samples.
* this is
* a list
* with a nested list
* and some subitems
* and here the parent list
continues
1. This is a numbered list.
2. It has two items too.
#. This is a numbered list.
#. It has two items too.

5. More Formatting
.. This is a comment.
.. This whole indented
block is a comment.
Still in the comment.
.. image:: path/to/image.png
.. raw:: html
<div>This is raw HTML</div>
This is a paragraph that contains `a link`_.
.. _a link: https://domain.invalid/
:: some literal text
This may also be used inline at the end of a paragraph, like so::
some more literal text

6. Tables
+------------------------+------------+----------+----------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+============+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2 | ... | ... | |
+------------------------+------------+----------+----------+
===== ===== =======
A B A and B
===== ===== =======
False False False
True False False
False True False
True True True
===== ===== =======
Other supported Table formats:
CSV Table:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#csv-table
List Table:
https://docutils.sourceforge.io/docs/ref/rst/directives.html#list-table

7. Cautions
Use a plain-text
editor only
• Notepad++, Vim
etc.
1
Don’t use
WYSIWYG
editors
• MS word, textEdit,
Notepad etc.
2
Use uniform
underlines for
headings in all
files
3
Keep track for
indentation,
whitespace &
blank-lines in rst
file
4

8. Sphinx
• Tool that converts rst to HTML
• Multiple skins (themes) available
• Plugins available for extending
• Complete list of formatting options supported by sphinx
https://www.sphinx-
doc.org/en/master/usage/restructuredtext/basics.html

9. One-time
Setup
Customize customize conf.py
Create Create Documentation Structure
Install Install required Sphinx plugins e.g. rtdtheme
Install Install Sphinx in virtual env
Create Create Python virtual env (best practice)
Install Install Python

10. Additional Best Practice – Use GIT
• Version control source files
• rst files
• conf.py
• GIT is common version control system
• Keeps the data safe
• Allows to pull old versions
• Allow seamless collaboration
More about source control and Git at
https://www.slideshare.net/AkshayMathur7/git-workshop-26088242

11. Resources
• Down & Install Python - No need to learn Python!
• https://www.python.org/downloads/
• Download & Install GIT [this also provides Linux shell on Windows]
• https://git-scm.com/downloads
• Create and activate virtual env
• https://docs.python.org/3/tutorial/venv.html#creating-virtual-environments
• Install Sphinx from pypi
• pip install -U sphinx
• https://www.sphinx-doc.org/en/master/usage/installation.html#installation-from-
pypi
• Install RTD Theme
• pip install sphinx_rtd_theme
• https://pypi.org/project/sphinx-rtd-theme/
• Theme config: https://sphinx-rtd-theme.readthedocs.io/en/stable/configuring.html

12. Resources
• Setup documentation source structure
• sphinx-quickstart
• https://www.sphinx-doc.org/en/master/usage/quickstart.html#setting-up-
the-documentation-sources
• Build Configuration file [conf.py]
• The file is generated with documentation source structure
• Options in file have include description
• https://www.sphinx-doc.org/en/master/usage/configuration.html
• Building [converting RST to HTML]
• sphinx-build sourcedir builddir
• https://www.sphinx-doc.org/en/master/usage/quickstart.html#running-the-
build