Improve documentation of functionality

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>`.

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

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
 ----------------
 

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_{}"