Page History
- 2020-Aug-05 17:35 coatsworth
- 2020-Jul-02 10:24 karpel
- 2020-Jul-02 09:34 karpel
- 2020-Apr-17 12:45 karpel
- 2020-Apr-17 12:22 karpel
- 2020-Apr-17 11:51 karpel
- 2020-Apr-15 17:52 coatsworth
- 2019-Nov-21 17:38 coatsworth
- 2019-Nov-15 09:57 karpel
- 2019-Sep-23 09:41 karpel
- 2019-Aug-28 09:47 karpel
- 2019-May-10 15:29 coatsworth
- 2019-May-09 16:38 coatsworth
- 2019-May-07 11:46 coatsworth
- 2019-May-03 14:26 coatsworth
- 2019-Apr-02 14:49 karpel
- 2019-Mar-29 12:39 coatsworth
- 2019-Mar-28 19:08 coatsworth
- 2019-Mar-28 17:05 coatsworth
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
- Install Python. Any version is fine.
- Install Sphinx. The recommended way to install Sphinx is via pip:
sudo pip install sphinx sphinx_rtd_theme
- 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 yourPYTHONPATH
environment variable to point at the.so
files inside your HTCondor install. Note: on RTD itself, the docs are built using thehtcondor
version specified indocs/requirements.txt
. - [Optional] Install python-docutils. This is only needed if you want to generate man pages for the manual:
sudo yum install python-docutils
- [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
sphinx-autobuild
.
Building
Building and previewing the manual locally
- The manual pages exist in our git repository under the
/docs
folder - Each top-level section of the manual has a corresponding subdirectory with the same name. For example, all the content for "Overview" is under
/docs/overview
, the content for "User's Manual" is under/docs/users-manual
, and so on. - Each page of the manual has a corresponding file with the same name and a .rst extension. For example, the content for the "Overview > Exceptional Features" page is in
/docs/overview/exceptional-features.rst
- To make a local build of the manual, go to your
/docs
folder and run:make html
- To preview your build, open a web browser and go to the following URL:
file:///<path-to-condor-src>/docs/_build/html/index.html
- To clean your local build, go to your
/docs
folder and run:make clean
Using sphinx-autobuild to build and preview
Instead of the instructions in the previous section, go to /docs
and run
sphinx-autobuild . _build/html
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
- Read the Docs allows us to host multiple versions of the manual. We'll have two separate versions: "latest" (equivalent to Development Release) and "stable" (equivalent to Stable Release).
- To make edits to the latest version, make your changes on the master branch.
- To make edits to the stable version, make your changes to the V8_8-branch (or the appropriate V8_8_X-branch if making your changes after code freeze)
Publishing
Publishing the manual onto Read the Docs
- Currently Mark or Josh has to login to Read the Docs to manually push any changes.
- Before we go live in May 2019, we'll set up a webhook in our git repository. This will cause any changes to get pushed automatically.
Generating man pages
- The files in
/docs/man-pages
will be the official source for our man pages going forward. - You can use the
rst2man
utility (included in thepython-docutils
package mentioned above) to convert these .rst files into man pages, for example:rst2man /docs/man-pages/condor_submit.rst /usr/share/man/man1/condor_submit.1