Automating Python Documentation with Sphinx

Every project is tied to strict deadlines for releases, often leaving no time for documentation after completing tasks like code reviews, automation, and unit tests. Code documentation is crucial for guiding users to use the code without any errors. However, it is often overlooked or deprioritized due to the perception that it's tedious. In this blog, we'll delve into how Sphinx Quickstart can help you get started with Python code documentation, enabling users to automatically & efficiently generate HTML and PDF code documentation for a Math project without coding HTML pages. Some of the companies like Mollie, Avito, and Craigslist are already using Sphinx for documentation.

Below are the key steps to get started with Python code documentation.

• Install Sphinx and automatically create a Sphinx doc structure with Sphinx Quickstart.

• Create an HTML homepage.

• Use Sphinx API Doc and Sphinx Extensions to create API-Style documentation automatically.

• Change Sphinx Theme and use reStructured Text to convert in-code docstrings to HTML documentation.

Note: Some of the tools used in automatic Python API documentation generation are pdoc, PyDoc, and Doxygen. Companies like Mollie, Avito, and Craigslist use Sphinx for Python code documentation.

Installing Sphinx and Using Sphinx Ǫuickstart

Pre-requisite: Install Python’s package
1. Install pip and upgrade to the latest version

2. Install Sphinx package and sphinx RTD theme

3. A directory structure is required for Sphinx to operate, which can be cloned from GitHub Repository. Create a root folder as Sphinx_basics and the math folder should contain the Python code to be documented. All the documentation will be under the docs folder - the main directory for Sphinx as  shown in the project structure below

4. On Command line, open the docs directory and use Sphinx Quickstart to generate the required files

5. Provide appropriate answers to the message prompts:

a.  How to set up the source and build directories that Sphinx will use. Enter y for this prompt.
b. Enter the name of the project, the root folder name, author names (multiple authors separated by a comma), project release, and language to generate the documentation.

6. Sphinx Quickstart will populate the docs/directory with subdirectories and files. The new project structure is as below.

The files and directories Sphinx Quickstart created are as follows:

a. build/: Directory where the HTML and PDF documentation files will be stored once generated.
b. source/: Directory contains the source code and files used to generate the documentation.
c. _static/: Folder for static HTML files to be used. This directory will remain empty.
d. _templates/: Folder to store HTML templates for custom HTML pages. This directory will remain empty.
e. conf.py: Python configuration file controls extensions and templates that Sphinx will use.
f. index.rst: reStructuredText file to generate HTML files in Markdown format to generate HTML  and PDF documentation. The index.rst is used to generate index.html, the homepage.
g. make.bat: Compilation file for Windows and Makefile: Compilation file for non-Windows.

Creating an Initial HTML Home Page

Sphinx Quickstart is used to generate the basic structure of documentation.

1. Add the root project path to the conf.py file to point Sphinx to the code.
2. Use Python’s built-in os and sys packages to add the root project path to the working path. Import the two packages and use the sys.path.insert() to insert them into the working path. Use the os package to define the absolute path to insert.

3. To generate HTML website files, use the Makefile in the docs/directory. Open ~sphinx basics/docs and run make HTML.

Sphinx generates HTML files in build/html. The index.rst is the reStructuredText file used to create the home page. If opened in a browser, it will be the home page of HTML website for the code.

Generating Documentation from Source Code

Note: To manually add content using reStructuredText syntax refer: reStructuredText documentation for more details.

Sphinx API Doc and Sphinx Extension generate documentation from source code.
The sphinx-apidoc CLI command takes source code and generates corresponding .rst files to create HTML documentation in API style for the input code. The command to specify the input source code and to specify where to output the .rst files is- 

To document the math, input code is math/module and output directory is docs/sources directory that generates the HTML code, and the .rst files can be found in the right location. Open the /docs directory and execute the command.

The modules.rst is a reStructuredText file that Sphinx automatically generates to encompass all the modules to be created. A .rst file is created for each module. Sphinx does not support generating code documentation from source code, but the auto doc extension allows it. To add extensions to Sphinx compilation, Open conf.py, and navigate to project variables where there is an empty list called extensions used to define extensions to use while compiling. Add autodoc extension to automatically generate documentation from source code, and add the viewcode extension, to get a link in the documentation to view the associated source code.

To generate the HTML documentation, modify the index.rst file to point to the modules.rst file when recreating the HTML. Go to the index.rst file and add modules.

Installing Sphinx Themes

To change the theme of documentation, Open conf.py, go to html_theme variable (by default alabaster), and change it to sphinx_rtd_theme.

Conclusion / Output

To view the final output, Open index.html in a browser, and navigate to the Calculator module to see the new code definitions. Congratulations! This is the landing page of the Sphinx Documentation!

To rebuild HTML, Go to docs folder and enter the below commands.