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.
Steps involved in generating HTML documentation:
- Open any existing Python project.
- Ensure project’s modules/classes/functions are documented using PEP 257 - Docstring Convention.
- Install Sphinx tool using
pip install sphinxin project’s virtual environment.
- Create a folder called
docswithin the project folder. We are going to install Sphinx related artifacts in this folder.
- Navigate to the
docsfolder and execute
sphinx-quickstartcommand 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:
makeutility - Utility used to generate html documentation
- index.rst - Index page in reStructuredText format
- conf.py - Mainly contains configuration information entered during sphinx-quickstart command
- 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
# 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('..'))
conf.py to include below extensions:
extensions = [ 'sphinx.ext.autodoc', 'sphinx.ext.viewcode' ]
- To generate HTML documentation, run
make htmlcommand from docs folder.
- Once the above command is successful, generated html documentation can be found in the
docs/htmlfolder of the project.
- Here is the generated HTML output taken from my sample project's environment: