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:

• sphinx_lesson.directives - see Directives.

• sphinx_lesson.md_transforms - see Markdown transforms.

• Enables the myst_notebook extension, which also enables myst_parser (included as a dependencies)

• Enables the sphinx-copybutton extension (included as a dependency)

• Same for sphinx-tabs

• Same for sphinx-togglebutton

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