Sphinx
Links
- Sphinx: https://www.sphinx-doc.org/
- Sphinx GitHub: https://github.com/sphinx-doc/sphinx/
- reStructuredText (reST): https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
- reStructuredText Primer: https://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
- Configuration: https://www.sphinx-doc.org/en/master/usage/configuration.html
- Table of Contents: https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#table-of-contents
- Cross-referencing Python objects
Extensions and Themes
- ABlog: https://ablog.readthedocs.io/
- MyST - Markedly Structured Text: https://myst-parser.readthedocs.io/
- MyST-NB: https://myst-nb.readthedocs.io/
- markdown-it-py: https://markdown-it-py.readthedocs.io/
- recommonmark: https://recommonmark.readthedocs.io/
- Napoleon: https://www.sphinx-doc.org/en/master/usage/extensions/napoleon.html
- Read the Docs Sphinx Theme: https://sphinx-rtd-theme.readthedocs.io/
- PyData Sphinx Theme: https://pydata-sphinx-theme.readthedocs.io/
Know-how
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:
SPHINXOPTS ?= -W
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,
}
Commands
- convert reStructuredText to Markdown:
pandoc -s -t commonmark -o <target>.md <source>.rst
Last modified July 13, 2023: Update sphinx.md (3eeea25)