41 lines
1.2 KiB
ReStructuredText
41 lines
1.2 KiB
ReStructuredText
Sphinx
|
|
======
|
|
|
|
`Sphinx <http://www.sphinx-doc.org/en/stable/>`_ is a tool for generating
|
|
documentation from `reStructuredText
|
|
<http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html>`_.
|
|
|
|
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 <https://github.com/emcrisostomo/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
|
|
<https://pypi.python.org/pypi/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/
|