Improve docs

changelog/11387.feature.rst

@@ -1,4 +1,5 @@
-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>`.
+Added the new :confval:`verbosity_assertions` configuration option for fine-grained control of failed assertions verbosity.
+
+See :ref:`Fine-grained verbosity <pytest.fine_grained_verbosity>` for more details.
+
+For plugin authors, :attr:`config.output_verbosity <pytest.Config.output_verbosity>` can be used to retrieve the verbosity level for a specific :class:`pytest.VerbosityType`.

doc/en/reference/reference.rst

@@ -1841,7 +1841,7 @@ passed multiple times. The expected format is ``name=value``. For example::
         [pytest]
         verbosity_assertions = 2
 
-    Defaults to application wide verbosity level.
+    Defaults to application wide verbosity level (via the ``-v`` command-line option).
 
 
 .. confval:: xfail_strict

src/_pytest/config/__init__.py

@@ -1021,7 +1021,12 @@ class Config:
         )
         self.args_source = Config.ArgsSource.ARGS
         self.args: List[str] = []
+
         self.output_verbosity = OutputVerbosity(self)
+        """Access to output verbosity configuration.
+
+        :type: OutputVerbosity
+        """
 
         if TYPE_CHECKING:
             from _pytest.cacheprovider import Cache
@@ -1667,21 +1672,25 @@ class Config:
 class VerbosityType(Enum):
     """Fine-grained verbosity categories."""
 
-    #: Application wide (default)
+    #: Application wide, controlled by ``-v``/``-q``.
     Global = "global"
+
+    #: Verbosity for failed assertions (see :confval:`verbosity_assertions`).
     Assertions = "assertions"
 
 
 class OutputVerbosity:
     r"""Access to fine-grained verbosity levels.
 
+    Access via :attr:`config.output_verbosity <pytest.Config.output_verbosity>`.
+
     .. code-block:: ini
 
         # content of pytest.ini
         [pytest]
         verbosity_assertions = 2
 
-    .. code-block:: bash
+    .. code-block:: console
 
         pytest -v
 
@@ -1699,7 +1708,11 @@ class OutputVerbosity:
 
     @property
     def verbose(self) -> int:
-        """Application wide verbosity level."""
+        """
+        Application wide verbosity level.
+
+        Same as the traditional ``config.getoption("verbose")``.
+        """
         assert isinstance(self._config.option.verbose, int)
         return self._config.option.verbose