Page History

Turn Off History

Overview

In 2019 we migrated the HTCondor Manual from our old LaTeX format into the Sphinx documentation generator using the reStructuredText format. We will also be hosting it on Read the Docs. The manual can be found here:

http://htcondor.readthedocs.io

Prerequisites

  1. Install Python. Any version is fine.

  2. Install Sphinx. The recommended way to install Sphinx is via pip:
    sudo pip install sphinx sphinx_rtd_theme
    
    On RHEL and CentOS we do not support installing Sphinx from yum or RPM. The available package is an old version which does not support all our extensions. For other Linux distributions, Windows and macOS, you can find instructions here:

  3. Install the HTCondor Python bindings. This could be via pip (make sure you get the right version, e.g. pip install htcondor==8.8.1), or by editing your PYTHONPATH environment variable to point at the .so files inside your HTCondor install. Note: on RTD itself, the docs are built using the htcondor version specified in docs/requirements.txt.

  4. [Optional] Install python-docutils. This is only needed if you want to generate man pages for the manual:
    sudo yum install python-docutils
    

  5. [Optional] Install https://pypi.org/project/sphinx-autobuild/. This is useful if you're making lots of quick edits to the manual and expect to build it many times.
    pip install sphinx-autobuild
    
    See below for instructions on using sphinx-autobuild.

Building

Building and previewing the manual locally

Using sphinx-autobuild to build and preview

Instead of the instructions in the previous section, go to /docs and run

sphinx-autobuild . _build/html
You will see a log of the Sphinx build running, and eventually will be provided a link to a localhost webserver hosting the docs. Leave this program running: sphinx-autobuild will watch the docs source tree for changes and rebuild when it detects changes (you will still need to manually reload the page inside your web browser).

Different versions of the manual

Editing

The manual now uses the reStructuredText (rST) format, which is similar to Markdown markup but considerably more powerful. A helpful reference to reStructuredText is available here:

http://docutils.sourceforge.net/docs/user/rst/quickref.html

In addition, the new manual also uses the Sphinx documentation generator. Sphinx does many useful things such as:

A full Sphinx reference is available here:

http://www.sphinx-doc.org/en/master/contents.html

This section provides some markup style guidelines, as well as information about how we use both built-in and custom tools.

Publishing

Publishing the manual onto Read the Docs

Generating man pages