{section: Read the Docs 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

{section: Prerequisites}

1: Install Python (https://www.python.org/downloads, or you system package manager). *You must install Python 3+*. We no longer support Python 2.

1: Install Sphinx and related support packages. The recommended way to install Sphinx is via `pip`, and we recommend using our pinned dependencies:
{code}
pip3 install --user -r docs/requirements.txt
{endcode}
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:
*::https://www.sphinx-doc.org/en/master/usage/installation.html

1: Install pandoc. On RHEL, for example:
{code}
sudo yum install pandoc
{endcode}
Windows and Mac installers can be found at https://github.com/jgm/pandoc/releases/

1: Install the HTCondor Python bindings.
This could be via =pip= (make sure you get the right version, e.g. =pip3 install htcondor==8.8.1=), or by editing your =PYTHONPATH= environment variable to point at the packages in your HTCondor build.
For example (replacing =<htcondor-release-dir>= with your local release directory path):
{code}
export PYTHONPATH=<htcondor-release-dir>/lib/python3:$PYTHONPATH
{endcode}
Note: on RTD, the docs are built using the pip-installed =htcondor= version read out of =CMakeLists.txt=, and the package versions in =docs/requirements.txt=.

1: If you're on Python <= 3.4 (editorial note: why?!), install the =pathlib= compatibility module:
{code}
pip3 install --user pathlib
{endcode}

1: [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.
{code}
pip3 install --user sphinx-autobuild
{endcode}
See below for instructions on using =sphinx-autobuild=.

{section: Building}

{subsection: 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:
{code}
make html
{endcode}
*:: 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:
{code}
make clean
{endcode}

{subsection: Using sphinx-autobuild to build and preview}

Instead of the instructions in the previous section, go to =/docs= and run
{code}
sphinx-autobuild . _build/html
{endcode}
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 may still need to manually reload the page inside your web browser, but it will usually force a refresh by itself).

{subsection: 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)

{section: Formatting Guidelines}

See the {wiki: ManualFormattingGuidelines Manual Formatting Guidelines} page.

{section: Publishing}

{subsection: Publishing the manual onto Read the Docs}

*:: Currently Mark or Josh has to login to Read the Docs to manually push any changes.

{subsection: Different versions of the manual}

*:: To make changes to the devel/latest version of the manual, put all your changes in the master branch.
*:: To make changes to the stable version of the manual, you need to add a tag called "stable" to the commit in V8_8-branch that contains the changes you want. To update the stable tag to a new commit, run the following:
{code}
git tag --delete stable
git push --delete origin tag stable
git tag stable
git push origin stable
{endcode}

{subsection: Generating man pages}

*:: The files in =/docs/man-pages= will be the official source for our man pages going forward.
*:: Sphinx can generate the man pages automatically. They will get output by default to the =/docs/_build/man= folder. From the =/docs= folder, run:
{code}
make man
{endcode}