Sphinx

I have been experimenting with Sphinx as a documentation tool. One of the reasons I have been thinking about moving to Sphinx for documentation is that it is easier to share and edit that LaTeX, but all the context easy to port over to a LaTeX format. Given that I have content written with sphinx, it is relatively easy to either create HTML files to publish to a website or generate LaTeX files. This means that the difficulty of creating equations and storing diagrams is largely preserved using Sphinx.

Creating a New Document

Math Support

https://www.sphinx-doc.org/en/1.0/ext/math.html

Citations

I recommend putting citations within the sphinx document, because finding documentation after the fact is difficult.

To provide links to a bibliography

pip install sphinxcontrib-bibtex

add the following line to the conf.py

extensions = ['sphinxcontrib.bibtex']

with the minimal documentation for a citation within a document, where ref.bib is a file in the same directory as the .rst file

See :cite:`1987:nelson` for an introduction to non-standard analysis.

.. bibliography:: refs.bib

References:

• Matthias C. M. Troffaes . Getting Started -- sphinxcontribbibtex 1.0.1a documentation. https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html. [Accessed 2/28/2020]

UML diagrams

Install the sphinx extension

pip install -U sphinxcontrib-plantuml

Then configure it in the conf.py

extensions = ['sphinxcontrib.plantuml']

Example:

.. uml::

   Alice -> Bob: Hi!

   Alice <- Bob: How are you?

References:

• https://pypi.org/project/sphinxcontrib-plantuml/