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: +1: Install the Python pathlib module: {code} -sudo yum install python-docutils +sudo pip install 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} -pip install sphinx-autobuild +sudo pip install sphinx-autobuild {endcode} See below for instructions on using =sphinx-autobuild=. @@ -86,7 +86,7 @@ {subsection: Section Titles} -Section titles are very fluid in rST and there are many different ways to make them. To keep things as consistent as possible, please use the following: +Section titles are very fluid in rST and there are many different ways to make them. To keep things as consistent as possible, try to use the following: {code} Page titles get underlined with the = symbol @@ -146,6 +146,20 @@ :index:`Name of index entry <single: Name of index entry; Name of parent entry>` {endcode} +{subsection: Linking to internal documents} + +To add a link to an internal document, the syntax looks like =:doc:`/path/to/page-title`=. For example, to link to the Overview > Exceptional Features section, add the following: + +{code} +:doc:`/overview/exceptional-features` +{endcode} + +By default, the link text will be the name of the page. If you want to add custom text, it looks something like the following: + +{code} +:doc:`Here is my custom text link </overview/exceptional-features>` +{endcode} + {section: Publishing} {subsection: Publishing the manual onto Read the Docs} @@ -156,7 +170,7 @@ {subsection: 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 the =python-docutils= package mentioned above) to convert these .rst files into man pages, for example: +*:: 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} -rst2man /docs/man-pages/condor_submit.rst /usr/share/man/man1/condor_submit.1 +make man {endcode}