How to generate professional documentation with Sphinx?
Tags: python, beginners, tutorial
Published: 2020-06-11 00:12:08

**Sphinx** is a tool that makes it easy to generate professional documentation for software projects. This tool can generate beautiful documentation in HTML, PDF, epub and many other output formats. It was originally developed to create Python documentation. Later generalized to work with any project.

Sphinx uses **reStructuredText** as its markup language. It has a DocUtils suite that parses and translates Python Docstrings into markup language which is then used to generate HTML or PDF.

In this article, let’s see how to get started with Sphinx by going over high level steps involved in generating HTML documentation for a simple Python project documented using Docstring Convention.

<h4>Steps involved in generating HTML documentation:</h4>

* Open any existing Python project.
* Ensure project’s modules/classes/functions are documented using <a href="https://www.python.org/dev/peps/pep-0257/">PEP 257 - Docstring Convention</a>.
* Install Sphinx tool using `pip install sphinx` in project’s virtual environment.
* Create a folder called `docs` within the project folder. We are going to install Sphinx related artifacts in this folder.
* Navigate to the `docs` folder and execute `sphinx-quickstart` command in the command line. When invoked, this utility asks simple questions about the project. Choosing default values should be sufficient. 
* Sphinx quick-start command generates files and folders which aids in generating HTML documentation. 
* Here is a high-level breakdown of artifacts generated using Sphinx quick-start command:
  1. `make` utility - Utility used to generate html documentation
  2. index.rst - Index page in reStructuredText format 
  3. conf.py - Mainly contains configuration information entered during sphinx-quickstart command
  4. Other static HTML folders
* To generate reStructuredText markup for the python package. Run `sphinx-apidoc -o docs <package folder>/` command from **project’s root** folder. This will generate files with **.rst** extension in docs folder.
* Before generating HTML documentation, below customization have to be done to `conf.py`
```python
# OS path commands should be uncommented in conf.py file
# so that html utility could access the right project files to 
# generate documentation. 
import os
import sys
sys.path.insert(0, os.path.abspath('..'))
```
Also, update `conf.py` to include below extensions:
```python
extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.viewcode'
]
```   
* To generate HTML documentation, run `make html` command from **docs** folder.
* Once the above command is successful, generated html documentation can be found in the `docs/html` folder of the project. 
* Here is the generated HTML output taken from my sample project's environment:

![index_page](https://dev-to-uploads.s3.amazonaws.com/i/oja3xihphng716f7ztam.png)

![modules_index](https://dev-to-uploads.s3.amazonaws.com/i/mo1mid47l0zt3gjbr20a.png)

![package_view](https://dev-to-uploads.s3.amazonaws.com/i/ijjr8j0v67avy00o6ao5.png)

![package_source_code_view](https://dev-to-uploads.s3.amazonaws.com/i/amoo34jsoh2a2nu915lk.png)

<h4>Further Reading</h4>
* <a href="https://www.sphinx-doc.org/en/master/index.html">Sphinx Documentation</a>
* <a href="https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html">reStructuredText</a>