Sphinx Installation¶

Sphinx¶

sudo apt install python3-sphinx

Hint

Further packages can be installed to extend either the theme (Example: python3-sphinx-bootstrap-theme) or to install extensions (Example: python3-sphinxcontrib.nwdiag). Themes and extensions need to be activated and configured in your conf.py. See Sphinx configuration.

Sphinx with live-preview¶

You may want to preview your documents before to publish on productive side.

sudo apt install python3-sphinx-autobuild

Hint

python3-autobuild is not nessesary to build your project. It enables the live-preview feature.

Extend your Makefile to include following target rule.

.PHONY: livehtml
livehtml:
     make clean 2>/dev/null
     mkdir $(BUILDDIR)/html
     sphinx-autobuild -q \
             -p 0 \
             --open-browser \
             --delay 5 \
             --ignore "*.swp" \
             --ignore "*.swx \
             --ignore "*.swpx \
             --ignore "*.pdf" \
             --ignore "*.log" \
             --ignore "*.out" \
             --ignore "*.toc" \
             --ignore "*.aux" \
             --ignore "*.idx" \
             --ignore "*.ind" \
             --ignore "*.ilg" \
             --ignore "*.tex" \
             --ignore ".git/*" \
             -b html $(SPHINXOPTS) "$(SOURCEDIR)" "$(BUILDDIR)/html"

After this you may execute make livehtml. This will automatically connects your webbrowser to a local port and refreshes the browser while watching in real time for the changes.

Pushing to a web server with a Git repository¶

With a git repository and a ssh trigger on the server side it is possible to pupulate content easily and safely on a web-browser. As such the ssh trigger script can abort tho build process on errors. Meanwhile the author uses sphinx-autobuild with make livehtml to preview his changes before pushing changes.

FIXME