Python Documentation: Generating HTML using Sphinx
This is part2 of the Python Documentation series. If you need help getting started with writing the documentation, you can take a look at part1
In this part, we will look at generating HTML files from the Python code docstrings. We will be using Sphinx for that. You can install sphinx via Pip
pip install sphinx
Sphinx typically works with ReStructured Text (.rst) files, but we can add support for Markdown(.md) files via m2r2
pip install m2r2
And we are done! Just kidding, but all that remains is updating few files and running few commands 😌
Note: Before generating docs, make sure that your codebase is a package (contains __init__.py at relevant locations)
Create a folder to store your docs and quick start the sphinx-setup:
mkdir docs && cd docssphinx-quickstart -q -p "<Project>" -a "<Author>" -v "<Version>"
You should see something similar to the following inside your docs directory:
Next, we need to update the conf.py (primary control / config file)
- Uncomment and Update the paths to make out python package visible
- Load sphinx extensions. You can read about the extensions in detail here
extensions = [
'sphinx.ext.napoleon', # Supports Google / Numpy docstring
'sphinx.ext.autodoc', # Documentation from docstrings
'sphinx.ext.doctest', # Test snippets in documentation
'sphinx.ext.todo', # to-do syntax highlighting
'sphinx.ext.ifconfig', # Content based configuration
'm2r2' # Markdown support
- Add supported file extensions for documentation
source_suffix = [‘.rst’, ‘.md’]
You can customise your conf.py upto any extent (changing theme, adding support for latex, etc.
Now, we are ready to generate our documentation. The final build commands looks for .rst/.md files to generate html. Either you can manually write the files or use sphinx-apidoc to automatically do it for you.
sphinx-apidoc -f -o . ../
You will see new .rst files, including a modules.rst inside your docs folder. We need to update this file inside our main index.rst
Welcome to Projects's documentation!
To add .md file, you will need to follow the syntax (instead of simply using .rst file name)
.. mdinclude:: ../README.md
Finally, we can build our rst / md files
If all goes well, you will have html files generated inside docs/_build/html/
You can ignore some of the warnings, if they look irrelevant.
You can manually check the webpages by starting a python http server and redirect to the aforementioned directory in the browser (localhost:8000)
python –m http.server
You should be able to see some fancy website containing the documentation of your module.