| 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. |