gitea-pages/admin-guide/mgmt-tools/sphinx.rst

Sphinx

Sphinx is a tool for generating documentation from reStructuredText.

It can generate various formats, including HTML and PDF.

Installing Sphinx

On RHEL 7 it is enough to install the python-sphinx package:

yum install python-sphinx

Editing

On Linux with the inotify-tools it is easy to have the documentation recompiled automatically while editing. Just run the following in the base directory of the documentation:

inotifywait --monitor --recursive --event close_write --exclude '_build' . | while read l; do make html;done

On OSX you can install fswatch and then run the following:

fswatch --exclude=_build --monitor=fsevents_monitor --recursive --event Updated --event Created --event Renamed .| while read l; do make html ;done

An even better alternative is sphinx-autobuild, which can be installed using pip:

pip install sphinx-autobuild

It can then be called like this:

sphinx-autobuild /path/to/sphinx/repo /path/to/sphinx/repo/_build/html/