How to get started with Sphinx for your Python project.
Making a documentation website for your python project can be daunting and would tradiationally reauire some web-dev skills. But Sphinx can be used to generate documentations for your project, it can be used to convert your docstrings and in code documentation into various output formats like HTML, PDF, LATEX, man-pages, etc.
- You have proper documentation for your code. This includes doc strings.
- Make sure that your doc strings follow a standard, eg. PEP, Google, Numpy, etc.
- Highly recommended to use a linter for both your code and docs, like Ruff (my personal favorite).
To tutorial contains some dummy code and documentation, for you to try out sphinx.
* To follow on first clone this repo.
* Go ahead and delete the src/docs diretory.
- for Ubuntu/Debian :
sudo apt install python3-sphinx
Refer for more details: Sphinx Installation
I like my docs as a separate folder in src. Therefore, I create a new directory docs.
And many fellow developers seems to use the same convention.
├── src │ ├── docs │ ├── package_dir │ │ ├── __init__.py │ │ ├── module_1.py │ │ ├── module_2.py │ │ ├── subpackage_dir │ │ │ ├── __init__.py │ │ │ ├── module_1.py │ │ │ ├── module_2.py ├── other directories and files not documented │ ├── css │ │ ├── **/*.css │ ├── images │ ├── js │ ├── index.html ├── pyproject.toml ├── requirements.txt ├── package-lock.json └── .gitignore
- Create a
docsdirectory insrc.
- Change your location to the previously created docs directory.
- Run:
`
sphinx-quickstart
`
This will ask you the following:
Do you wanna separate your build and source?
N, Since I recommend a folder structure with a separate docs directory.
Name of Project
Author Name(s)
Project Release
Project Language
If run successfully this will create a conf.py file, the make files and folders like _build, _static, and _template.
- Change your location to the src directory.
- Run:
`
sphinx-apidoc -o docs package_dir
`
where the package_dir is my_calculator for this tutorial.
Note that: here `-o` flag is the output folder, in our structure this is the `docs` directory, and `package_dir` is the directory with all the code you want to document.
This will create .rst files for each Python module and package.
The conf.py file should be in docs folder. You can see all the details you specified during the quickstart command here.
Add the following to the beginning of conf.py.
`
import os
import sys
sys.path.insert(0, os.path.abspath(".."))
`
Note that this assumes the above-mentioned folder structure, if you have a different structure, make sure to point it to the source code.
Sphinx has a lot of useful extensions. These should be added to the extensions tag. Some of the extensions I use are:
sphinx.ext.autodoc- This extension automatically takes doc strings from your python files.sphinx.ext.linkcode(Optional) - This extension provides a link to the GitHub code. (Note that this extension requires other configs. Refer to Sphinx extension documentation for more details.)sphinx.ext.viewcode(Optional) - This extension is similar to the above extension, instead of linking the code to GitHub, it displays the code in a static webpage.sphinx.ext.napoleon(Optional) - If you write your doc strings using Numpy or Google standard, you need this extension.
An example extentions in the conf.py file.
extensions = [
"sphinx.ext.autodoc",
"sphinx.ext.todo",
"sphinx.ext.napoleon",
"sphinx.ext.linkcode",
]
I use a Sphinx theme, which can be installed by running,
`
pip install sphinx-rtd-theme
`
- Change the html_theme tag in the conf.py to sphinx_rtd_theme.
`
html_theme = 'sphinx_rtd_theme'
`
You can find more themes at various sources like www.sphinx-themes.org/, https://sphinxthemes.com, etc.
To finally generate the docs run the following command from the docs directory.
`
make html
`
This will create a _build directory, where you can find the html files. Opening the index.html shows you the homepage of your docs.
Note that whenever you have any changes to your code or documentation, you just have to run the above command and Sphinx will update your documentation.
- To add other pages to your sphinx website, you just have to create .rst reStructuredText files in the appropriate location and add them to your index.rst or to the toctree of a file already mentioned in index.rst.
- For more instructions on defining document structure refer Defining Docuement Structure
- For instructions on how to format reStructuredText refer to reStructuredText Basics
- To follow on this tutorial, copy this
README.rstfile tosrc/docsand add the following theREADMEfile on the toctree. Like shown below
> .. toctree:: > :maxdepth: 2 > :caption: Contents: > > mycalculator > readme