Merge pull request pytest-dev#7510 from bluetech/docstrings

Format docstrings in a consistent style

Author: bluetech

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

doc/en/reference.rst

@@ -182,7 +182,7 @@ Mark a test function as using the given fixture names.
 
 .. py:function:: pytest.mark.usefixtures(*names)
 
-    :param args: the names of the fixture to use, as strings
+    :param args: The names of the fixture to use, as strings.
 
 .. note::
 
@@ -209,8 +209,10 @@ Marks a test function as *expected to fail*.
         Condition for marking the test function as xfail (``True/False`` or a
         :ref:`condition string <string conditions>`). If a bool, you also have
         to specify ``reason`` (see :ref:`condition string <string conditions>`).
-    :keyword str reason: Reason why the test function is marked as xfail.
-    :keyword Exception raises: Exception subclass expected to be raised by the test function; other exceptions will fail the test.
+    :keyword str reason:
+        Reason why the test function is marked as xfail.
+    :keyword Type[Exception] raises:
+        Exception subclass expected to be raised by the test function; other exceptions will fail the test.
     :keyword bool run:
         If the test function should actually be executed. If ``False``, the function will always xfail and will
         not be executed (useful if a function is segfaulting).
@@ -224,7 +226,7 @@ Marks a test function as *expected to fail*.
           a new release of a library fixes a known bug).
 
 
-custom marks
+Custom marks
 ~~~~~~~~~~~~
 
 Marks are created dynamically using the factory object ``pytest.mark`` and applied as a decorator.
@@ -473,7 +475,7 @@ caplog
 .. autofunction:: _pytest.logging.caplog()
     :no-auto-options:
 
-    This returns a :class:`_pytest.logging.LogCaptureFixture` instance.
+    Returns a :class:`_pytest.logging.LogCaptureFixture` instance.
 
 .. autoclass:: _pytest.logging.LogCaptureFixture
     :members:
@@ -491,7 +493,7 @@ monkeypatch
 .. autofunction:: _pytest.monkeypatch.monkeypatch()
     :no-auto-options:
 
-    This returns a :class:`MonkeyPatch` instance.
+    Returns a :class:`MonkeyPatch` instance.
 
 .. autoclass:: _pytest.monkeypatch.MonkeyPatch
     :members:

src/_pytest/_argcomplete.py

@@ -1,7 +1,8 @@
-"""allow bash-completion for argparse with argcomplete if installed
-needs argcomplete>=0.5.6 for python 3.2/3.3 (older versions fail
+"""Allow bash-completion for argparse with argcomplete if installed.
+
+Needs argcomplete>=0.5.6 for python 3.2/3.3 (older versions fail
 to find the magic string, so _ARGCOMPLETE env. var is never set, and
-this does not need special code.
+this does not need special code).
 
 Function try_argcomplete(parser) should be called directly before
 the call to ArgumentParser.parse_args().
@@ -10,8 +11,7 @@
 arguments specification, in order to get "dirname/" after "dirn<TAB>"
 instead of the default "dirname ":
 
-   optparser.add_argument(Config._file_or_dir, nargs='*'
-                               ).completer=filescompleter
+   optparser.add_argument(Config._file_or_dir, nargs='*').completer=filescompleter
 
 Other, application specific, completers should go in the file
 doing the add_argument calls as they need to be specified as .completer
@@ -20,35 +20,43 @@
 
 SPEEDUP
 =======
+
 The generic argcomplete script for bash-completion
-(/etc/bash_completion.d/python-argcomplete.sh )
+(/etc/bash_completion.d/python-argcomplete.sh)
 uses a python program to determine startup script generated by pip.
 You can speed up completion somewhat by changing this script to include
   # PYTHON_ARGCOMPLETE_OK
 so the the python-argcomplete-check-easy-install-script does not
 need to be called to find the entry point of the code and see if that is
-marked  with PYTHON_ARGCOMPLETE_OK
+marked  with PYTHON_ARGCOMPLETE_OK.
 
 INSTALL/DEBUGGING
 =================
+
 To include this support in another application that has setup.py generated
 scripts:
-- add the line:
+
+- Add the line:
     # PYTHON_ARGCOMPLETE_OK
-  near the top of the main python entry point
-- include in the file calling parse_args():
+  near the top of the main python entry point.
+
+- Include in the file calling parse_args():
     from _argcomplete import try_argcomplete, filescompleter
-   , call try_argcomplete just before parse_args(), and optionally add
-   filescompleter to the positional arguments' add_argument()
+  Call try_argcomplete just before parse_args(), and optionally add
+  filescompleter to the positional arguments' add_argument().
+
 If things do not work right away:
-- switch on argcomplete debugging with (also helpful when doing custom
+
+- Switch on argcomplete debugging with (also helpful when doing custom
   completers):
     export _ARC_DEBUG=1
-- run:
+
+- Run:
     python-argcomplete-check-easy-install-script $(which appname)
     echo $?
-  will echo 0 if the magic line has been found, 1 if not
-- sometimes it helps to find early on errors using:
+  will echo 0 if the magic line has been found, 1 if not.
+
+- Sometimes it helps to find early on errors using:
     _ARGCOMPLETE=1 _ARC_DEBUG=1 appname
   which should throw a KeyError: 'COMPLINE' (which is properly set by the
   global argcomplete script).
@@ -63,29 +71,29 @@
 
 
 class FastFilesCompleter:
-    "Fast file completer class"
+    """Fast file completer class."""
 
     def __init__(self, directories: bool = True) -> None:
         self.directories = directories
 
     def __call__(self, prefix: str, **kwargs: Any) -> List[str]:
-        """only called on non option completions"""
+        # Only called on non option completions.
         if os.path.sep in prefix[1:]:
             prefix_dir = len(os.path.dirname(prefix) + os.path.sep)
         else:
             prefix_dir = 0
         completion = []
         globbed = []
         if "*" not in prefix and "?" not in prefix:
-            # we are on unix, otherwise no bash
+            # We are on unix, otherwise no bash.
             if not prefix or prefix[-1] == os.path.sep:
                 globbed.extend(glob(prefix + ".*"))
             prefix += "*"
         globbed.extend(glob(prefix))
         for x in sorted(globbed):
             if os.path.isdir(x):
                 x += "/"
-            # append stripping the prefix (like bash, not like compgen)
+            # Append stripping the prefix (like bash, not like compgen).
             completion.append(x[prefix_dir:])
         return completion