Extensions and Themes#


Turn warnings into errors#

It is possible to turn warnings into errors. This way a build fails when something is wrong. To do this edit the Makefile of Sphinx and change this line:


Also see: https://www.sphinx-doc.org/en/master/man/sphinx-build.html#cmdoption-sphinx-build-W

MyST Syntax#

  • add a link to a locale PDF or other file - source

{download}`text <_static/reference.pdf>`

May.la Installation#

  • create repo on GitHub and clone it

  • chane into the repo directory

  • run sphinx-quickstart - say yes here:

You have two options for placing the build directory for Sphinx output.
Either, you use a directory "_build" within the root path, or you separate
"source" and "build" directories within the root path.
> Separate source and build directories (y/n) [n]:
  • delete make.bat - we do not work with windows

  • config git with git config pull.rebase true

  • install https://sphinx-rtd-theme.readthedocs.io/en/latest/

  • install https://myst-nb.readthedocs.io/en/latest/

    • add it to extensions

    • turn off notebook building: jupyter_execute_notebooks = "off"

  • turn off prev_next_buttons:

html_theme_options = {
    "prev_next_buttons_location": None,


  • convert reStructuredText to Markdown: pandoc -s -t commonmark -o <target>.md <source>.rst