:doc:`Here is my custom text link </overview/exceptional-features>` {endcode} +{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<something>::= 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<something>::= in the appropriate =.rst=. + {section: Publishing} {subsection: Publishing the manual onto Read the Docs}