===================
Sphinx Installation
===================

Sphinx
======

.. code-block:: bash

   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 :doc:`configuration`.

Sphinx with live-preview
========================

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

.. code-block:: bash

   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.

.. code-block:: none

   .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