1.1. Setup#

1.1.1. Instruction#

Requirements

Python > 3.8

Installation

Install the theme

python -m pip install sphinx
python -m pip install sphinx-theme-mochi

Create a new project

sphinx-quickstart .

Edit conf.py to change the theme

# conf.py
html_theme = 'sphinx_theme_mochi'

Add the theme to the list of extensions.

extensions = [
    'sphinx.ext.todo',
    'sphinx.ext.autodoc',
    'sphinx.ext.mathjax',
    'myst_parser',
    'sphinx_theme_mochi',
]

sphinx-autobuild watches local files and rebuilds the document when changed.

python -m pip install sphinx-autobuild

run, then open the browser to preview (defaults to localhost:8000)

sphinx-autobuild <source> <build/html> -E
# -E: fresh build (no-cache)

Add a markdown parser in the list of extensions for markdown syntax support. MyST-parser is a parser designed for Sphinx (and Docutils).

python -m pip install myst_parser

extensions = [
    'myst_parser',
]

Sphinx has math equation support for both html/non-html. For html output, sphinx can use image-renderer or mathjax-renderer for math rendering.

To use mathjax renderer, add the mathjax extension to the extensions list, and set mathjax_path to the script. See Official docs for details.

#conf.py
mathjax_path = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js'

Download the javascript for local distribution. For offline environment, you might need to use file:// URL.

pip install sphinx-mathjax-offline