For other Linux distributions, Windows and macOS, you can find instructions here: *::https://www.sphinx-doc.org/en/master/usage/installation.html +1: 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=. + 1: [Optional] Install python-docutils. This is only needed if you want to generate man pages for the manual: {code} sudo yum install python-docutils {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} +pip install sphinx-autobuild +{endcode} +See below for instructions on using =sphinx-autobuild=. {section: Building} @@ -41,13 +50,21 @@ 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 will still need to manually reload the page inside your web browser). + {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: Publishing} {subsection: Publishing the manual onto Read the Docs}