Document Generation

Site documentation is generated using sphinx with a python virtual environment and a custom makefile.


If python3-pip and python3-venv are installed, the virtual environment will be created automatically and built with make. See Python Virtual Environments for manual steps.

Documentation should be linkchecked for linkrot before building a new set of docs to be published.

One shot build and link verification.
make clean docs linkcheck
Build docs, then verify links separately.
make clean docs
make linkcheck
Clean docs/ to upload only source changes.
make head


master file […] checkouts/latest/contents.rst not found

Usually occurs when no sphinx modules are found in the python environment. Ensure environment is properly and retry. See Using Virtual Environments.

Additionally, you may force specify an alternative index in using master_doc = 'index'. See contents.rst issue.

Manual Installation

  1. See Python Virtual Environments to setup a working environment.

  2. Install sphinx and sphinx plugins.

Install packages from environment requirements.
. {ENV DIR}/bin/activate
python3 -m pip install --requirement sphinx/requirements.txt
  1. Use custom file for site customization.

0640 user user docs/sphinx/
# Configuration file for the Sphinx documentation builder.
# This file only contains a selection of the most common options. For a full
# list see the documentation:

# -- 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.
import os
import sys
import sphinx_rtd_theme
sys.path.insert(0, os.path.abspath('./_ext'))

# -- Project information -----------------------------------------------------

project = 'Generic service & computer documentation.'
copyright = '2019, r-pufky'
author = 'r-pufky'

# -- General configuration ---------------------------------------------------

# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = [

# Expand default Read the Docs page width
def setup(app):

# pygments doesn't handle powershell well. Ignore warnings for code-blocks.
suppress_warnings = ['misc.highlighting_failure']

# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']

# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['Thumbs.db', '.DS_Store']

today_fmt = '%Y-%m-%d'

# Include TODOs.
todo_include_todos = True

# ConfigTable separator

# aafig: Empty format for CheckExternalLinksBuilder (linkchecking) is required.
aafig_format = {
  'html': 'svg',
  'latex': 'pdf',
  'text': None,
  '': None
aafig_default_options = {
  'textual': True,

# linkchecker exceptions. See:
linkcheck_ignore = [
  # Broken: local state/context needed to resolve.
  # Broken: Will timeout after too many requests.
  # Broken: github dynamically adds anchors and cannot be checked.
  # Redirects: latest tags are always redirected to versions on github.
  # Redirects: behind authentication wall.
  # Redirects: youtube now redirects with next video.
  # Temporarily disable for repo DMCA.
linkcheck_workers = 10

# HTML rendering
# The theme to use for HTML and HTML Help pages.  See the documentation for
# a list of builtin themes.
html_theme = 'sphinx_rtd_theme'
html_theme_path = ['_themes']
html_theme_options = {
  'collapse_navigation': False,
  'navigation_depth': -1,
html_show_sourcelink = False
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']


  1. Video Tutorial on Sphinx

  2. Sphinx Getting Started Tutorial

  3. Ascii Art Figure Manual

  4. Ascii Art Figure Documentation

  5. RST Primer Tutorial

  6. RST Live Editor

  7. Sphinx Live Editor

  8. Sphinx RST Cheetsheet

  9. Sphinx RST Cheetsheet 2

  10. Sphinx roles and subsitutions

  11. Sublime and Sphinx

  12. nginx Sphinx documentation guidance

  13. Sphinx Tools

Development References

  1. Sphinx Development

  2. Documented List

  3. RST Directive option conversion functions

  4. Sphinx roles

  5. docutils snippets

  6. Unicode Python 3 escape sequences

  7. Unicode triangular bullet

  8. Using sphinx with github

  9. Custom Sphinx Makefile