Sphinx

Sphinx is the engine behind this site. It uses the following directory structure:

docs/
├── source/
│   ├── conf.py     # Sphinx configuration file
│   ├── index.rst   # Root reStructuredText file for the site
│   └── ...         # Other reStructuredText files for the site
└── _build/         # Directory for built HTML files
│   └── html/       # Generated static site
└── requirements.txt  # Project dependencies

It reads the .rst files under source/ and turns them into a static site in _build/html. The behavior of the site is configured in source/conf.py.

Extensions enabled in conf.py for this project:

extensions = [
    'sphinx.ext.extlinks',
    'sphinx.ext.intersphinx',
    'sphinx.ext.todo',
    'ablog',
    'sphinxcontrib.youtube',
    'sphinx.ext.mathjax',
    'sphinx-mathjax-offline',
    'numpydoc',
    'sphinx.ext.graphviz',
    'sphinx_design',
]

The site uses the pydata_sphinx_theme HTML theme (set via html_theme in conf.py). sphinx_design provides the cards and grids on the home page, and sphinx.ext.graphviz needs Graphviz’s dot on the PATH.

To build the HTML pages locally:

$ sphinx-build -M html source _build          # writes to _build/html
$ python -m http.server -d _build/html        # preview at localhost:8000