Docstrings in DataLad source code are used and consumed in many ways. Besides serving as documentation directly in the sources, they are also transformed and rendered in various ways.
Sphinx-rendered documentation for the Python API and the command line API
A common source docstring is transformed, amended and tuned specifically for each consumption scenario.
Formatting overview and guidelines
In general, the docstring format follows the NumPy standard. In addition, we follow the guidelines of Restructured Text with the additional features and treatments provided by Sphinx, and some custom formatting outlined below.
Additions, changes, or deprecation should be recorded in a docstring using the
standard Sphinx directives
.. deprecated:: 0.16 The ``dryrun||--dryrun`` option will be removed in a future release, use the renamed ``dry_run||--dry-run`` option instead.
PY macros can be used to selectively include documentation
for specific APIs only:
options to pass to :command:`git init`. [PY: Options can be given as a list of command line arguments or as a GitPython-style option dictionary PY][CMD: Any argument specified after the destination path of the repository will be passed to git-init as-is CMD].
For API-alternative command and argument specifications the following format can be used:
where the double backticks are mandatory and
<cmdline-part> represent the respective argument specification for each
API. In these specifications only valid argument/command names are allowed,
plus a comma character to list multiples, and the dot character to include an
When automatic transformations negatively affect the presentation of a
docstring due to excessive removal of content, leaving “holes”, the
macro can be used to enclose such segments, in order to reformat them
as the final processing step. Example:
|| REFLOW >> The API has been aligned with the some ``create_sibling_...||create-sibling-...`` commands of other GitHub-like services, such as GOGS, GIN, GitTea.<< REFLOW ||
The start macro must appear on a dedicated line.