Sphinx is the open-source tool for converting reStructured Text into various formats for publishing product documentation. This deck talks about getting started with authoring documentation using Sphinx
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
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
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