Cleanup the docs a bit.

Author: ionelmc

README.rst

@@ -13,6 +13,7 @@ Overview
       - |github-actions|
     * - package
       - |version| |conda-forge| |wheel| |supported-versions| |supported-implementations| |commits-since|
+
 .. |docs| image:: https://readthedocs.org/projects/pytest-cov/badge/?style=flat
     :target: https://readthedocs.org/projects/pytest-cov/
     :alt: Documentation Status
@@ -45,10 +46,11 @@ Overview
 
 .. end-badges
 
-This plugin produces coverage reports. Compared to just using ``coverage run`` this plugin does some extras:
+This plugin provides coverage functionality as a pytest plugin. Compared to just using ``coverage run`` this plugin does some extras:
 
-* Subprocess support: you can fork or run stuff in a subprocess and will get covered without any fuss.
-* Xdist support: you can use all of pytest-xdist's features and still get coverage.
+* Automatic erasing and combination of .coverage files and default reporting.
+* Support for detailed coverage contexts (add ``--cov-context=test`` to have the full test name including parametrization as the context).
+* Xdist support: you can use all of pytest-xdist's features including remote interpreters and still get coverage.
 * Consistent pytest behavior. If you run ``coverage run -m pytest`` you will have slightly different ``sys.path`` (CWD will be
   in it, unlike when running ``pytest``).
 
@@ -68,11 +70,10 @@ For distributed testing support install pytest-xdist::
 
     pip install pytest-xdist
 
-Upgrading from ancient pytest-cov
----------------------------------
+Upgrading from pytest-cov 6.3
+-----------------------------
 
-`pytest-cov 2.0` is using a new ``.pth`` file (``pytest-cov.pth``). You may want to manually remove the older
-``init_cov_core.pth`` from site-packages as it's not automatically removed.
+`pytest-cov 6.3` and older were using a ``.pth`` file to enable coverage measurements in subprocesses. This was removed in `pytest-cov 7` - use `coverage's patch options <https://coverage.readthedocs.io/en/latest/config.html#run-patch>`_ to enable subprocess measurements.
 
 Uninstalling
 ------------
@@ -111,10 +112,6 @@ Documentation
 https://pytest-cov.readthedocs.io/en/latest/
 
 
-
-
-
-
 Coverage Data File
 ==================
 
@@ -132,12 +129,6 @@ For distributed testing the workers must have the pytest-cov package installed.
 the plugin must be registered through setuptools for pytest to start the plugin on the
 worker.
 
-For subprocess measurement environment variables must make it from the main process to the
-subprocess. The python used by the subprocess must have pytest-cov installed. The subprocess must
-do normal site initialisation so that the environment variables can be detected and coverage
-started. See the `subprocess support docs <https://pytest-cov.readthedocs.io/en/latest/subprocess-support.html>`_
-for more details of how this works.
-
 Security
 ========
 

docs/reporting.rst

@@ -3,12 +3,12 @@ Reporting
 
 It is possible to generate any combination of the reports for a single test run.
 
-The available reports are terminal (with or without missing line numbers shown), HTML, XML, JSON, Markdown (either in 'write' or 'append' mode to file), LCOV and
-annotated source code.
+The available reports are terminal (with or without missing line numbers shown), HTML, XML, JSON, Markdown (either in 'write' or 'append'
+mode to file), LCOV and annotated source code.
 
-The terminal report without line numbers (default)::
+The default is terminal report without line numbers::
 
-    pytest --cov-report term --cov=myproj tests/
+    pytest --cov=myproj tests/
 
     -------------------- coverage: platform linux2, python 2.6.4-final-0 ---------------------
     Name                 Stmts   Miss  Cover
@@ -22,7 +22,7 @@ The terminal report without line numbers (default)::
 
 The terminal report with line numbers::
 
-    pytest --cov-report term-missing --cov=myproj tests/
+    pytest --cov-report=term-missing --cov=myproj tests/
 
     -------------------- coverage: platform linux2, python 2.6.4-final-0 ---------------------
     Name                 Stmts   Miss  Cover   Missing
@@ -49,32 +49,45 @@ The terminal report with skip covered::
 
 You can use ``skip-covered`` with ``term-missing`` as well. e.g. ``--cov-report term-missing:skip-covered``
 
-The report options below output to files without showing anything on the terminal::
+If any reporting options are used then the default (``--cov-report=term`` is not added automatically). For example this would not show any
+terminal output:
+
+.. code-block:: bash
 
     pytest --cov-report html
-            --cov-report xml
-            --cov-report json
-            --cov-report markdown
-            --cov-report markdown-append:cov-append.md
-            --cov-report lcov
-            --cov-report annotate
-            --cov=myproj tests/
-
-The output location for each of these reports can be specified. The output location for the XML, JSON, Markdown and LCOV
-report is a file. markdown-append option is specially useful for appending the report to an existing file. Example for GitHub Actions:
---cov-report=markdown-append:${GITHUB_STEP_SUMMARY}. Where as the output location for the HTML and annotated source code reports are
-directories::
+           --cov-report xml
+           --cov-report json
+           --cov-report markdown
+           --cov-report markdown-append:cov-append.md
+           --cov-report lcov
+           --cov-report annotate
+           --cov=myproj tests/
+
+You can specify output paths for reports. The output location for the XML, JSON, Markdown and LCOV
+report is a file. Where as the output location for the HTML and annotated source code reports are
+directories:
+
+.. code-block:: bash
 
     pytest --cov-report html:cov_html
-            --cov-report xml:cov.xml
-            --cov-report json:cov.json
-            --cov-report markdown:cov.md
-            --cov-report markdown-append:cov-append.md
-            --cov-report lcov:cov.info
-            --cov-report annotate:cov_annotate
-            --cov=myproj tests/
-
-The final report option can also suppress printing to the terminal::
+           --cov-report xml:cov.xml
+           --cov-report json:cov.json
+           --cov-report markdown:cov.md
+           --cov-report markdown-append:cov-append.md
+           --cov-report lcov:cov.info
+           --cov-report annotate:cov_annotate
+           --cov=myproj tests/
+
+Example for GitHub Actions with ``markdown-append``:
+
+.. code-block:: bash
+
+    pytest --cov-report=markdown-append:${GITHUB_STEP_SUMMARY}.
+           --cov=myproj tests/
+
+To disable the default ``term`` report provide an empty report:
+
+.. code-block:: bash
 
     pytest --cov-report= --cov=myproj tests/