Sphinx and Myst Syntax to write the documentation#
Introduction to the Sphinx documentation system#
Sphinx is the official documentation system used by the Python community (and far behond). It was originally designed for the RestructuredText markup language, which it has expanded on. Since then, Markdown has become the de facto standard to write technical documentation.
Luckily, the people around the Jupyter Project have started a new ecosystem of tools allowing the write Sphinx documentation with an extended version of Markdown called MyST Markdown. This page gives a little bit of context around the Myst toolchain.
Since RestructuredTest is “the mother tongue” of the Sphinx documentation, the reference documentation is still written with this language in mind.
Sphinx official documentation
The Sphinx official documentation can be found under https://www.sphinx-doc.org/en/master/.
Advantages of writing the documentation with Sphinx#
One advantage of writing the documentation with Sphinx and Markdown is that Sphinx can easily generate a static HTML site with the whole content and a LaTeX version for paper. It is possible to write some custom part specifically targetted for the online version and other parts for the written part.
It can therefore allow a “Documentation first” writing of a thesis that could follow steps like
Write the documentation for the project
Convert the relevant parts to LaTeX and include it in the thesis right away.
General introduction using the RST language#
The following video gives a general introduction to the Sphinx documentation system. The first part is presentation and not relevant.
Introduction to using Sphinx with Myst/Markdown syntax#
The following video gives an introduction to using Sphinx with MyST/Markdown.
Documentation and reference material for MyST#
The MyST markdown is an extension of the Markdown to make it on paar with RestructuredText, allowing to use Sphinx roles and directives and to be powerful enough to write a book or a thesis with cross-references, bibliography, figures and a lot more.
Official MyST documentation#
Other good references and tutorials#
Documentation of the Sphinx Book Theme (used by this very documentation) : https://sphinx-book-theme.readthedocs.io/en/stable/index.html. This gives a lot of tips and tricks about using Sphinx with MyST/Markdown and the Sphinx Book Theme.
Courses about Sphinx#
Static sites with Sphinx and Markdown
The following free course shows how to write good documentation using the Sphinx and MyST/Markdown combination : https://training.talkpython.fm/courses/static-sites-with-sphinx-and-markdown
Various tools#
Myst tools : https://myst-tools.org/. Toolchain to generate LaTeX from MyST files.
Tool to convert RestructuredText to Myst executablebooks/rst-to-myst
Tool to write pandoc filters in Python (could be useful to convert MyST to LaTeX) : sergiocorreia/panflute
Extensions#
The following extensions could be very useful to write the documentation efficiently.
executablebooks/sphinx-tabs : Sphinx tabs
executablebooks/sphinx-copybutton : Copy code into clipboard
https://sphinx-panels.readthedocs.io/en/latest/#panels-usage
sphinx-contrib/kroki : integrate various diagram tools
https://sphinxcontrib-platformpicker.readthedocs.io/en/stable/usage.html
https://champollion.readthedocs.io/en/stable/ : automatically document Javascript code based on JSDocs comments
https://sphinx-imgur.readthedocs.io/en/v3.0.0/usage.html : Include images from imgur
sphinx-contrib/aafig Include aafig figures. Fork of it with python 3 fixes : 13pgeiser/sphinx-aafig
kleynjan/sphinx-jinja-ext : use Jinja templates
https://sphinx.silverrainz.me/recentupdate/ : allows to show recent updates based on git commits
missinglinkelectronics/sphinxcontrib-scalebybuilder Scale images differently based on builder
isaksamsten/sphinx_simpleversion Version documentation
engineerjoe440/sphinx_docbook : convert to DocBook
vhiribarren/sphinxcontrib-itemlist : reference items from list or table
https://default-values.readthedocs.io/en/latest/ : document default values
sphinx-toolbox/sphinx-highlights : Beautiful Highlights
nyergler/tut : Usefull to write tutorials as it allows to output the diff between different states of a file based on different git branches.
Special extensions#
hackbrightacademy/sphinx-lectern : make lecture notes and slideshow from Sphinx documentation
magmax/jinyaml : allows to define Jinja templates
Could be useful for click-based CLI program#
VSCode extension#
Essentially Sphinx snippets to speed up writing in VSCode.