Various docs improvements

Signed-off-by: Andreas Maier <andreas.r.maier@gmx.de>

README.rst

@@ -37,27 +37,31 @@ help find issues with garbage collection and memory leaks:
   into which the object to be released is involved. The garbage collector is
   designed to handle circular references when releasing objects.
 
+  Collected objects are not a problem per se, but they can contribute to
+  large memory use and can often be eliminated.
+
 * It can determine the set of *uncollectable objects* caused by a function or
   method.
 
   Uncollectable objects are objects Python was unable to release during garbage
   collection, even when running a full collection (i.e. on all generations of
-  the Python generational garbage collector). Uncollectable objects remain
-  allocated in the last generation of the garbage collector. On each run on
-  its last generation, the garbage collector attempts to release these objects.
-  It seems to be rare that these continued attempts eventually succeed, so
-  these objects can basically be considered memory leaks.
+  the Python generational garbage collector).
+
+  Uncollectable objects remain allocated in the last generation of the garbage
+  collector. On each run on its last generation, the garbage collector attempts
+  to release these objects. It seems to be rare that these continued attempts
+  eventually succeed, so these objects can basically be considered memory leaks.
 
 See section
 `Background`_
 for more detailed explanations about object release in Python.
 
 Yagot is simple to use in either of the following ways:
 
-* It provides a `pytest`_ plugin that detects collected and uncollectable
-  objects caused by the test cases. This detection is enabled by specifying
-  command line options or environment variables and does not require modifying
-  the test cases.
+* It provides a `pytest`_ plugin named ``yagot`` that detects collected and
+  uncollectable objects caused by the test cases. This detection is enabled by
+  specifying command line options or environment variables and does not require
+  modifying the test cases.
 
 * It provides a Python decorator named
   `garbage_checked`_
@@ -95,8 +99,8 @@ Usage
 -----
 
 Here is an example of how to use Yagot to detect collected objects caused by
-pytest test cases using the command line options provided by the pytest plugin
-of Yagot:
+pytest test cases using the command line options provided by the
+yagot pytest plugin:
 
 .. code-block:: text
 
@@ -148,7 +152,11 @@ of Yagot:
     =========================== 1 passed, 1 deselected, 1 error in 0.07s ===========================
 
 Here is an example of how to use Yagot to detect collected objects caused by a
-function using the ``garbage_checked`` decorator of Yagot on the function:
+function using the
+``garbage_checked``
+decorator on the function.
+The yagot pytest plugin is loaded in this example and it presence is reported
+by pytest, but it is not used:
 
 .. code-block:: text
 

docs/background.rst

@@ -26,13 +26,13 @@ Python has two mechanisms for releasing objects:
   it references are decreased by one, and the original object is immediately
   released.
 
+  Those referenced objects whose reference count drops to zero as a result of
+  being decreased will in turn be immediately released.
+
   If it triggers, this process always succeeds. If the original object is
   involved in circular references, the process does not trigger in the first
   place, because the reference count of the original object never drops to zero.
 
-  Those referenced objects whose reference count drops to zero as a result of
-  being decreased will in turn be immediately released.
-
 * Asynchronous release during garbage collection:
 
   Objects that can possibly be involved in circular references are tracked by
@@ -128,10 +128,9 @@ The issues with collected and uncollectable objects
 For short-running Python programs (e.g. command line utilities), it is mostly
 not so important if there are some memory leaks and other resource leaks. On
 most operating systems, resource cleanup at process termination is very thorough
-and resources such as open files are cleaned up properly. I'm not advocating to
-be careless there, in fact I would always recommend to also keep short-running
-Python programs clean, but the negative effect is less severe compared to
-long-running programs.
+and resources such as open files are cleaned up properly. This should not be
+understood as advocating to be careless there, but the negative effect is less
+severe on short-running programs compared to long-running programs.
 
 If your Python package provides modules for use by other code, you usually
 cannot predict whether it will be used in short-running or long-running

docs/development.rst

@@ -39,8 +39,7 @@ Setting up the development environment
    Have the virtual Python environment active for all remaining steps.
 
 3. Install the project for development.
-   This will install Python packages into the active Python environment,
-   and OS-level packages:
+   This will install Python packages into the active Python environment:
 
    .. code-block:: bash
 

docs/intro.rst

@@ -16,27 +16,32 @@ help find issues with garbage collection and memory leaks:
   into which the object to be released is involved. The garbage collector is
   designed to handle circular references when releasing objects.
 
+  Collected objects are not a problem per se, but they can contribute to
+  large memory use and can often be eliminated.
+
 * It can determine the set of *uncollectable objects* caused by a function or
   method.
 
   Uncollectable objects are objects Python was unable to release during garbage
   collection, even when running a full collection (i.e. on all generations of
-  the Python generational garbage collector). Uncollectable objects remain
-  allocated in the last generation of the garbage collector. On each run on
-  its last generation, the garbage collector attempts to release these objects.
-  It seems to be rare that these continued attempts eventually succeed, so
-  these objects can basically be considered memory leaks.
+  the Python generational garbage collector).
+
+  Uncollectable objects remain allocated in the last generation of the garbage
+  collector. On each run on its last generation, the garbage collector attempts
+  to release these objects. It seems to be rare that these continued attempts
+  eventually succeed, so these objects can basically be considered memory leaks.
 
 See section
 :ref:`Background`
 for more detailed explanations about object release in Python.
 
 Yagot is simple to use in either of the following ways:
 
-* It provides a `pytest`_ plugin that detects collected and uncollectable
-  objects caused by the test cases. This detection is enabled by specifying
-  command line options or environment variables and does not require modifying
-  the test cases.
+* It provides a `pytest`_ plugin named :ref:`yagot <Yagot pytest plugin>` that
+  detects collected and
+  uncollectable objects caused by the test cases. This detection is enabled by
+  specifying command line options or environment variables and does not require
+  modifying the test cases.
 
 * It provides a Python decorator named
   :func:`~yagot.garbage_checked`
@@ -57,8 +62,8 @@ Usage
 -----
 
 Here is an example of how to use Yagot to detect collected objects caused by
-pytest test cases using the command line options provided by the pytest plugin
-of Yagot:
+pytest test cases using the command line options provided by the
+:ref:`yagot pytest plugin`:
 
 .. code-block:: text
 
@@ -110,7 +115,11 @@ of Yagot:
     =========================== 1 passed, 1 deselected, 1 error in 0.07s ===========================
 
 Here is an example of how to use Yagot to detect collected objects caused by a
-function using the ``garbage_checked`` decorator of Yagot on the function:
+function using the
+:func:`~yagot.garbage_checked`
+decorator on the function.
+The yagot pytest plugin is loaded in this example and it presence is reported
+by pytest, but it is not used:
 
 .. code-block:: text
 
@@ -295,5 +304,16 @@ it to):
     $ python -c "import yagot; print('ok')"
     ok
 
+In addition, you can verify that pytest picks up the yagot plugin, by
+looking at the pytest help. If it shows the yagot options, the plugin
+has been properly picked up:
+
+.. code-block:: bash
+
+    $ pytest --help | grep yagot
+    --yagot               Enables checking for collected and uncollectable
+    --yagot-leaks-only    Limits the checking to only uncollectable (=leak)
+    --yagot-ignore-types=TYPE[,TYPE[...]]
+
 In case of trouble with the installation, see the :ref:`Troubleshooting`
 section.

docs/pytest.rst

@@ -1,13 +1,11 @@
 
-.. _`Pytest plugin`:
+.. _`Yagot pytest plugin`:
 
-Pytest plugin
-=============
+Yagot pytest plugin
+===================
 
-This section describes the pytest plugin of Yagot.
-
-The pytest plugin is automatically installed along with the yagot package.
-It adds the following group of command line options to pytest:
+The ``yagot`` pytest plugin is automatically installed along with the yagot
+package. It adds the following group of command line options to pytest:
 
 .. code-block:: text