diff options
author | Ran Benita <ran@unusedvar.com> | 2020-07-17 23:54:41 +0300 |
---|---|---|
committer | Ran Benita <ran@unusedvar.com> | 2020-08-01 17:14:38 +0300 |
commit | cbec0f8c6ad01a3987506c27d2c0d0706d479659 (patch) | |
tree | b4ba82717a21885d082c34ed34c12f13a499fa17 /CONTRIBUTING.rst | |
parent | 0242de4f5651818379bc0ff6326c97565a20a0f1 (diff) | |
download | pytest-cbec0f8c6ad01a3987506c27d2c0d0706d479659.tar.gz |
CONTRIBUTING: document the docstring style we use
Diffstat (limited to 'CONTRIBUTING.rst')
-rw-r--r-- | CONTRIBUTING.rst | 32 |
1 files changed, 32 insertions, 0 deletions
diff --git a/CONTRIBUTING.rst b/CONTRIBUTING.rst index 0523c0ece..4481fee38 100644 --- a/CONTRIBUTING.rst +++ b/CONTRIBUTING.rst @@ -89,6 +89,38 @@ without using a local copy. This can be convenient for small fixes. The built documentation should be available in ``doc/en/_build/html``, where 'en' refers to the documentation language. +Pytest has an API reference which in large part is +`generated automatically <https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html>`_ +from the docstrings of the documented items. Pytest uses the +`Sphinx docstring format <https://sphinx-rtd-tutorial.readthedocs.io/en/latest/docstrings.html>`_. +For example: + +.. code-block:: python + + def my_function(arg: ArgType) -> Foo: + """Do important stuff. + + More detailed info here, in separate paragraphs from the subject line. + Use proper sentences -- start sentences with capital letters and end + with periods. + + Can include annotated documentation: + + :param short_arg: An argument which determines stuff. + :param long_arg: + A long explanation which spans multiple lines, overflows + like this. + :returns: The result. + :raises ValueError: + Detailed information when this can happen. + + .. versionadded:: 6.0 + + Including types into the annotations above is not necessary when + type-hinting is being used (as in this example). + """ + + .. _submitplugin: Submitting Plugins to pytest-dev |