{section: Manual Formatting Guidelines} 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: *:: Converts reStructuredText files into HTML websites, PDF, EPUB and man pages. *:: Extends rST to provide more complex inline widgets such as tables of contents, syntax-colored code blocks, internal links and references, *:: Automatic indices, search and language-specific module indices *:: Provides a powerful API for writing custom extensions 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. {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, try to use the following: {code} Page titles get underlined with the = symbol ============================================ Section titles get underlined with the - symbol ----------------------------------------------- Subsection titles get underlined with the ' symbol '''''''''''''''''''''''''''''''''''''''''''''''''' {endcode} {subsection: Indentation} The rST format is very sensitive to indentation. Paragraphs and other blocks of text are expected to be left-aligned. Indenting a block by any amount of whitespace (compared to the preceding block) causes it to get indented. {code} This is a top-level block of text. It will appear aligned to the left-most side of the page. This paragraph is indented by one space. Even though it's only a single space, it will render as a full first-level indent. This paragraph is indented by one more space than the one above it. As a result it will render as a second-level indent. This time I've indented a block by two more spaces the one above it. It doesn't matter that this is inconsistent with the single-space indents above. This block will render as a third-level indent. Back to the top level! This block is indented by 12 spaces. However, as with the previous examples, the amount of whitespace doesn't matter. Because it's the first indented block compared to the preceding block, it will only render as a first-level indent. {endcode} {subsection: Referencing condor daemons} When describing the functionality of a condor daemon, its name should be enclosed in * characters so they appear in italics: {code} *condor_daemonname* {endcode} However when showing a usage example of a condor daemon as it would appear on the command line, its name should be enclosed in `` characters so it appears in fixed-width font, for example: {code} ``condor_q -nobatch -allusers`` {endcode} {subsection: Configuration macros} Any configuration macro references should be written with the following syntax: {code} :macro:`CONDOR_CONFIGURATION_MACRO_NAME` {endcode} This will make the macro appear as a clickable link to its definition. All macro definitions must be included on the {link: https://htcondor.readthedocs.io/en/latest/admin-manual/configuration-macros.html Configuration Macros} page in the manual. To add a new definition to this page, use the following syntax: {code} :macro-def:`CONDOR_CONFIGURATION_MACRO_NAME` This is the text that describes what the macro actually does. {endcode} Note that both the =:macro:= and =:macro-def:= names must have identical spelling; this is how we generate the HTML anchor to make sure that links point to the correct place. {subsection: Linking to gittrac tickets} Use the following syntax to automatically link to a gittrac ticket, where #### is the number of the ticket: {code} :ticket:`####` {endcode} {subsection: Adding index entries} To add a basic index entry, use the following syntax: {code} :index:`Name of index entry` {endcode} If you want your index entry to appear under a parent entry, the syntax is a little more complicated: {code} :index:`Name of index 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 ` {endcode} {subsection: Linking to subsections within documents} You can also easily add links to subsections within documents. Whenever a section or subsection is defined using the correct section title syntax (see "Section Titles" above), Sphinx will automatically make the an HTML anchor so you can link directly to it. Use the following syntax: {code} :ref:`path/to/document:section title` {endcode} For example, to link to the "Start an Annex" subsection on the Annex User's Guide page, use the following: {code} :ref:`cloud-computing/annex-users-guide:start an annex` {endcode} By default, Sphinx will use the name of the section as the link text. You can override this with the following syntax: {code} :ref:`My custom link text goes here` {endcode} {subsection: Syntax Highlighting} Sphinx can perform syntax highlighting in code blocks, and can sometimes automatically detect what language is in the block, but usually needs a hint to help it out. A code block with an explicit language looks like this: {code} .. code-block:: console $ condor_q -- Schedd: submit.chtc.wisc.edu : <127.0.0.1:9618?... @ 12/31/69 23:00:00 OWNER BATCH_NAME SUBMITTED DONE RUN IDLE HOLD TOTAL JOB_IDS nemo batch23 4/22 20:44 _ _ _ 1 _ 3671850.0 nemo batch24 4/22 20:56 _ _ _ 1 _ 3673477.0 nemo batch25 4/22 20:57 _ _ _ 1 _ 3673728.0 nemo batch26 4/23 10:44 _ _ _ 1 _ 3750339.0 nemo batch27 7/2 15:11 _ _ _ _ _ 7594591.0 nemo batch28 7/10 03:22 4428 3 _ _ 4434 7801943.0 ... 7858552.0 nemo batch29 7/14 14:18 5074 1182 30 19 80064 7859129.0 ... 7885217.0 nemo batch30 7/14 14:18 5172 1088 28 30 58310 7859106.0 ... 7885192.0 2388 jobs; 0 completed, 1 removed, 58 idle, 2276 running, 53 held, 0 suspended {endcode} Some common languages you may want to use: *: =console=: =bash= console sessions *: =bash=: =bash= scripts *: =doscon=: Windows CMD sessions *: =bat=: Windows BAT files *: =python=: Python scripts *: =pycon=: Python REPL sessions *: =pytb=: Python tracebacks *: =text=: plain text, no syntax highlighting We also have some custom lexers, defined in =full_conf.py=: *: =condor-classad=: A new or old-style ClassAd *: =condor-classad-expr=: A bare ClassAd language expression *: =condor-submit=: Condor submit language *: =condor-config=: Condor configuration language *: =condor-dagman=: DAGMan description files A full list of built-in lexers is available at https://pygments.org/docs/lexers/ {subsection: Documenting Python Objects} Python "objects" (classes, methods, free functions, enums, anything) are documented via =sphinx-autodoc= (https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html). "Docstrings" for these objects are written directly into the Python bindings C++ source code, are embedded into the Python library during the HTCondor build process, and are then read by Sphinx during the manual build. As an example, a method declaration (adding a method to a class) looks like this in the C++ source code: {code} .def("queue_with_itemdata", &Submit::queue_from_iter, R"C0ND0R( Submit the current object to a remote queue. :param txn: An active transaction object (see :meth:`Schedd.transaction`). :type txn: :class:`Transaction` :param int count: A queue count for each item from the iterator, defaults to 1. :param from: an iterator of strings or dictionaries containing the itemdata for each job as in ``queue in`` or ``queue from``. :return: a :class:`SubmitResult`, containing the cluster ID, cluster ClassAd and range of Job ids Cluster ID of the submitted job(s). :rtype: :class:`SubmitResult` :raises RuntimeError: if the submission fails. )C0ND0R", (boost::python::arg("self"), boost::python::arg("txn"), boost::python::arg("count")=1, boost::python::arg("itemdata")=boost::python::object()) ) {endcode} Note the use of a raw string delimited by =C0ND0R= for the docstring itself. The syntax is described here: https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html The corresponding =.rst= source that would embed this docstring, prettily-formatted, in the manual looks like {code} .. autoclass:: Submit .. automethod:: queue .. automethod:: queue_with_itemdata .. automethod:: expand .. automethod:: jobs .. automethod:: procs .. automethod:: itemdata .. automethod:: getQArgs .. automethod:: setQArgs .. automethod:: from_dag {endcode} The =.. auto::= are Sphinx directives provided by =sphinx-autodoc= which are replaced by the autodoc-formatted descriptions. So this block produces all of the documentation for the =Submit= object. When documenting a new thing in the bindings, you must also add an appropriate =.. auto::= in the appropriate =.rst=.