Sphinx documentation cheatsheet

sphinx-documentation.md

Overview

This document is a simple resource to create sphinx documentation for projects with python(or not). This isn't exhaustive, but it'll help us get started without much hassle, (which, is typical for sphinx generated documenting)

Prerequisites

For better results, ensure that you're inside a virtual env. This document assumes you're in a Pipenv based environment. Update it later to include other python package management tools (hopefully poetry)

For pipenv based environment.

• Activate the pipenv env with pipenv shell

• Install sphinx pipenv install --dev sphinx The --dev flag is recommended as having it outside development environment can (and most probably will) cause unnecessary annoying issues during production.

• Install sphinx extensions that are recommended.

• pipenv install --dev sphinxcontrib.httpdomain

• pipenv install --dev sphinxcontrib-mermaid This uses Mermaidjs to generate graph/diagrams that can be easily embedded in the document

• mkdir docs to create a docs directory and cd docs into it.

• Run sphinx-quickstart to utilize sphinx's quickstart to get yourself started with the defaults.

  • Most defaults are good to go. But you can consider changing them if you want to.

• Run make html to generate HTML documentation for your project.

  • If configured with the defaults, the generated document will be in the build directory. (./_build/html/index.html)

Additional guide to ensure you've configured other things to generate the documentation properly.

• You may have to enable the following extensions (These are some common extensions that I use. Add whatever you think is required)

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.coverage",
    "sphinx.ext.napoleon",
    "sphinxcontrib.httpdomain",
    "sphinxcontrib.autohttp.flask",
    "sphinxcontrib.autohttp.flaskqref",
]

And then run sphinx-apidoc ../<project_dir>/ -o ./

You better have a .editorconfig because spaces matter in ReST files and it'll cause you issues if you don't write it properly, or if your editor/IDE isn't properly configured

# Add the following to your .editorconfig so you manage rest files properly. 
[{*.rst,*.rst.txt}]
charset = utf-8
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true
indent_style = space
indent_size = 3

Ensure that you configure the path the sphinx builder needs to fetch the source files from. Now that you have your docs in a separate directory, it is essential you configure the path to the project directory in your docs/conf.py file.

# -- Path setup --------------------------------------------------------------

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.

# The following lines ensure that the path to your source files are defined. 
import os
import sys
sys.path.insert(0, os.path.abspath('.'))