Debian Codegraph @

docs/source/design/docstrings.rst

raw
1 .. -*- mode: rst -*-
2 .. vi: set ft=rst sts=4 ts=4 sw=4 et tw=79:
3
4 .. _chap_design_docstrings:
5
6 **********
7 Docstrings
8 **********
9
10 .. topic:: Specification scope and status
11
12 This specification provides a partial overview of the current
13 implementation.
14
15 Docstrings in DataLad source code are used and consumed in many ways. Besides
16 serving as documentation directly in the sources, they are also transformed
17 and rendered in various ways.
18
19 - Command line ``--help`` output
20 - Python's ``help()`` or IPython's ``?``
21 - Manpages
22 - Sphinx-rendered documentation for the Python API and the command line API
23
24 A common source docstring is transformed, amended and tuned specifically for
25 each consumption scenario.
26
27
28 Formatting overview and guidelines
29 ==================================
30
31 In general, the docstring format follows the `NumPy standard <https://numpydoc.readthedocs.io/en/latest/format.html#docstring-standard>`_.
32 In addition, we follow the guidelines of `Restructured Text <https://docutils.sourceforge.io/docs/user/rst/quickstart.html>`_ with the additional features and treatments provided by `Sphinx <https://www.sphinx-doc.org/en/master>`_, and some custom formatting outlined below.
33
34 Version information
35 -------------------
36
37 Additions, changes, or deprecation should be recorded in a docstring using the
38 standard Sphinx directives ``versionadded``, ``versionchanged``,
39 ``deprecated``::
40
41 .. deprecated:: 0.16
42 The ``dryrun||--dryrun`` option will be removed in a future release, use
43 the renamed ``dry_run||--dry-run`` option instead.
44
45
46 API-conditional docs
47 --------------------
48
49 The ``CMD`` and ``PY`` macros can be used to selectively include documentation
50 for specific APIs only::
51
52 options to pass to :command:`git init`. [PY: Options can be given as a list
53 of command line arguments or as a GitPython-style option dictionary PY][CMD:
54 Any argument specified after the destination path of the repository will be
55 passed to git-init as-is CMD].
56
57 For API-alternative command and argument specifications the following format
58 can be used::
59
60 ``<python-api>||<cmdline-api``
61
62 where the double backticks are mandatory and ``<python-part>`` and
63 ``<cmdline-part>`` represent the respective argument specification for each
64 API. In these specifications only valid argument/command names are allowed,
65 plus a comma character to list multiples, and the dot character to include an
66 ellipsis::
67
68 ``github_organization||-g,--github-organization``
69
70 ``create_sibling_...||create-sibling-...``
71
72
73 Reflow text
74 -----------
75
76 When automatic transformations negatively affect the presentation of a
77 docstring due to excessive removal of content, leaving "holes", the ``REFLOW``
78 macro can be used to enclose such segments, in order to reformat them
79 as the final processing step. Example::
80
81 || REFLOW >>
82 The API has been aligned with the some
83 ``create_sibling_...||create-sibling-...`` commands of other GitHub-like
84 services, such as GOGS, GIN, GitTea.<< REFLOW ||
85
86 The start macro must appear on a dedicated line.