Installation#

Sphinx Python package#

This is distributed as a normal Sphinx extension, so it is easy to use. To use it, install sphinx_lesson via PyPI.

Then, enable the extension in your Sphinx conf.py. This will both define our special directives, and load the other required extensions (myst_nb). The myst_nb extension can be configured normally:

extensions = [
    'sphinx_lesson',
]

HTML theme#

We are in theory compatible with any theme, but are most tested with the sphinx_rtd_theme (which you need to set yourself):

html_theme = 'sphinx_rtd_theme'

The Jupyter Book (Executable Books Project) Sphinx theme (sphinx-book-theme) has some very nice features and also deserves some consideration. Using it should be clear: html_theme = "sphinx_book_theme". You can see a preview of it as a branch on github-pages.

Under the hood#

Adding sphinx_lesson as an extension adds these sub-extensions:

Any of these can be used independently to get the same effect.