Documentation

How to document

pass

AOT substitutions

One problem with documentation (especially of parameters) is that one either duplicates (copy paste) a docstring for a parameter that is used in multiple places (such as the documentation of the "norm" of a PDF), or one substitutes it dynamically. The former is definitely not DRY, while the latter has the disadvantage that a) there is a lot of dynamizism going on when building the docs. Typically, a method is then decorated with something, and if that fails, it would fail the execution of the code. This should be separated. But more strikingly, b) as a developer, the documentation is not in real-time available

zfit opts for a third option: ahead-of-time substitutions that will be executed with pre-commit. There is a substitution file in utils/api, named argdocs.yaml, which contains keys that will be substituted and a python file, replace_argdocs.py that replaces the substitutions. To be precise, the content that will be inserted into the start and end of the directive. An example

"""|@doc:pdf.kde.bandwidth.weights||@docend:pdf.kde.bandwidth.weights|"""

will be written in docstrings. The key here is pdf.kde.bandwidth.weights.

Meanwhile, we need to add the docstring in the substitution file:

pdf.kde.bandwidth.weights: |1+
   Individual event weight of *data*.

with the docstring being "Individual event weight of *data*." (multiline is also possible, see other examples there).

Executing the pre-commit will render the above to

"""|@doc:pdf.kde.bandwidth.weights| Individual event weight of *data*. |@docend:pdf.kde.bandwidth.weights|"""

making the docstring accessible for developers.

When the docs get made, the commands |@doc:...| and |@docend:...| get replaced by a whitespace without size, so as to vanish for the viewers eyes.