From 4d7ceb8d9fc3c69d95166199abc097d537148f61 Mon Sep 17 00:00:00 2001
From: Patrick Lannigan <p.lannigan@gmail.com>
Date: Sun, 5 Nov 2023 14:51:46 -0500
Subject: [PATCH] Improve documentation of functionality

---
 changelog/11387.feature.rst    |  5 ++++-
 doc/en/how-to/output.rst       |  9 ++++++---
 doc/en/reference/reference.rst | 10 +++++++++-
 src/_pytest/config/__init__.py | 19 +++++++++++++++++++
 4 files changed, 38 insertions(+), 5 deletions(-)

diff --git a/changelog/11387.feature.rst b/changelog/11387.feature.rst
index d8d9f6a6a..891d7a747 100644
--- a/changelog/11387.feature.rst
+++ b/changelog/11387.feature.rst
@@ -1 +1,4 @@
-:confval:`verbosity_assertions` option added to be able to control assertion output independent of the application wide verbosity level.
+Added fine-grained verbosity support to override the application wide verbosity level.
+:class:`pytest.OutputVerbosity` can be used to retrieve the verbosity level for a specific :class:`pytest.VerbosityType`.
+:confval:`verbosity_assertions` option added to be able to control assertion output independent of the application wide
+verbosity level. See :ref:`Fine-grained verbosity <pytest.fine_grained_verbosity>`.
diff --git a/doc/en/how-to/output.rst b/doc/en/how-to/output.rst
index 3e401b3c6..5b9a777db 100644
--- a/doc/en/how-to/output.rst
+++ b/doc/en/how-to/output.rst
@@ -270,17 +270,20 @@ situations, for example you are shown even fixtures that start with ``_`` if you
 Using higher verbosity levels (``-vvv``, ``-vvvv``, ...) is supported, but has no effect in pytest itself at the moment,
 however some plugins might make use of higher verbosity.
 
+.. _`pytest.fine_grained_verbosity`:
+
 Fine-grained verbosity
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In addition to specifying the application wide verbosity level, it is possible to control specific aspects independently.
 This is done by setting a verbosity level in the configuration file for the specific aspect of the output.
 
-:confval:`verbosity_assertions`: Controls how verbose the assertion output should be when pytest is executed. A value of ``2``
-would have the same output as the previous example, but each test inside the file is shown by a single character in the
-output.
+:confval:`verbosity_assertions`: Controls how verbose the assertion output should be when pytest is executed. Running
+``pytest --no-header`` with a value of ``2`` would have the same output as the previous example, but each test inside
+the file is shown by a single character in the output.
 
 (Note: currently this is the only option available, but more might be added in the future).
+
 .. _`pytest.detailed_failed_tests_usage`:
 
 Producing a detailed summary report
diff --git a/doc/en/reference/reference.rst b/doc/en/reference/reference.rst
index 6605aafd2..68b282067 100644
--- a/doc/en/reference/reference.rst
+++ b/doc/en/reference/reference.rst
@@ -957,6 +957,15 @@ OptionGroup
 .. autoclass:: pytest.OptionGroup()
     :members:
 
+OutputVerbosity
+~~~~~~~~~~~~~~~
+
+.. autoclass:: pytest.OutputVerbosity()
+    :members:
+
+.. autoclass:: pytest.VerbosityType()
+    :members:
+
 PytestPluginManager
 ~~~~~~~~~~~~~~~~~~~
 
@@ -996,7 +1005,6 @@ Stash
     :show-inheritance:
     :members:
 
-
 Global Variables
 ----------------
 
diff --git a/src/_pytest/config/__init__.py b/src/_pytest/config/__init__.py
index 4b10608a0..e5a0db5f1 100644
--- a/src/_pytest/config/__init__.py
+++ b/src/_pytest/config/__init__.py
@@ -1667,11 +1667,30 @@ class Config:
 class VerbosityType(Enum):
     """Fine-grained verbosity categories."""
 
+    #: Application wide (default)
     Global = "global"
     Assertions = "assertions"
 
 
 class OutputVerbosity:
+    r"""Access to fine-grained verbosity levels.
+
+    .. code-block:: ini
+
+        # content of pytest.ini
+        [pytest]
+        verbosity_assertions = 2
+
+    .. code-block:: bash
+
+        pytest -v
+
+    .. code-block:: python
+
+        print(config.output_verbosity.get())  # 1
+        print(config.output_verbosity.get(VerbosityType.Assertions))  # 2
+    """
+
     DEFAULT = "auto"
     _option_name_fmt = "verbosity_{}"