Getting Started with Sphinx

Sphinx is based on Python so you should have Python installed on your system. Although it is possible to install Python and Sphinx in Windows, it's recommended to use a Linux distribution preferably Ubuntu for this purpose.

If your main OS is Windows, you can use VMWare or VirtualBox to install Ubuntu as a guest OS.

In order to start using Sphinx and generate documents first of all you need to install the Sphinx engine:

sudo apt-get install python3-sphinx

Then you should initialize your documentation build environment:

sphinx-quickstart

Having a nice theme brings some joy to your documentation and make it much more readable:

pip install sphinx-rtd-theme \
sphinx-ustack-theme \
sphinx-ansible-theme \
sphinx_redactor_theme

For more themes refer to Sphinx Themes

The default language supported in Sphinx is reStructuredText. If you prefer Markdown you can install it on Sphinx using this command:

pip install recommonmark

Some other useful packages for Sphinx:

pip install sphinx-prompt sphinxemoji

Whenever you want to generate the HTML output you can use this command:

make html

If you want to have a beautiful PDF output you should first install the LaTeX engine:

sudo apt-get install texlive-latex-recommended \
texlive-fonts-recommended \
texlive-latex-extra \
latexmk

Then by entering the following command the PDF output will be generated:

make latexpdf

Required packages for build process of Sphinx are put in a file called requirements.txt. Use the following command to install them:

pip install -r requirements.txt

If you need other packages to be installed on Sphinx, it is recommended to add them to this requirements.txt file.

---

To study more about Sphinx and reStructuredText please refer to the following links:

• reST & Sphinx Cheat Sheet
• reST & Sphinx Reference
• Getting Started with Sphinx
• Rest and Sphinx Memo
• Sphinx-RTD-Tutorial
• Code documentation lesson: Sphinx and reStructuredText
• Quick reStructuredText
• reStructuredText Primer
• Create Documentation with RST, Sphinx, Sublime, and GitHub