config: generalize from INI format

This prepares the code and documentation for adding another
configuration file format, TOML.

Add a `mode` field to `ConfigValue` to track the parsing mode.

Add tabs to all configuration file snippets in the docs, so that we may
show both toml and ini in a nice way once toml is added. Uses the
sphinx-inline-tabs package that I saw used by tox documentation.

Avoid references to "pytest.ini" and "ini file" in docs, instead refer
to "configuration file" (I'm sure I missed some).

Author: bluetech

doc/en/conf.py

@@ -34,6 +34,7 @@
     "sphinx.ext.todo",
     "sphinx.ext.viewcode",
     "sphinx_removed_in",
+    "sphinx_inline_tabs",
     "sphinxcontrib_trio",
     "sphinxcontrib.towncrier.ext",  # provides `towncrier-draft-entries` directive
     "sphinx_issues",  # implements `:issue:`, `:pr:` and other GH-related roles

doc/en/deprecations.rst

@@ -845,20 +845,24 @@ that manipulate this type of file (for example, Jenkins, Azure Pipelines, etc.).
 Users are recommended to try the new ``xunit2`` format and see if their tooling that consumes the JUnit
 XML file supports it.
 
-To use the new format, update your ``pytest.ini``:
+To use the new format, update your configuration file:
 
-.. code-block:: ini
+.. tab:: ini
 
-    [pytest]
-    junit_family=xunit2
+    .. code-block:: ini
+
+        [pytest]
+        junit_family = xunit2
 
 If you discover that your tooling does not support the new format, and want to keep using the
 legacy version, set the option to ``legacy`` instead:
 
-.. code-block:: ini
+.. tab:: ini
+
+    .. code-block:: ini
 
-    [pytest]
-    junit_family=legacy
+        [pytest]
+        junit_family = legacy
 
 By using ``legacy`` you will keep using the legacy/xunit1 format when upgrading to
 pytest 6.0, where the default format will be ``xunit2``.

doc/en/example/markers.rst

@@ -239,13 +239,14 @@ Registering markers
 
 Registering markers for your test suite is simple:
 
-.. code-block:: ini
+.. tab:: ini
 
-    # content of pytest.ini
-    [pytest]
-    markers =
-        webtest: mark a test as a webtest.
-        slow: mark test as slow.
+    .. code-block:: ini
+
+        [pytest]
+        markers =
+            webtest: mark a test as a webtest.
+            slow: mark test as slow.
 
 Multiple custom markers can be registered, by defining each one in its own line, as shown in above example.
 

doc/en/example/pythoncollection.rst

@@ -88,13 +88,14 @@ Example:
 Changing directory recursion
 -----------------------------------------------------
 
-You can set the :confval:`norecursedirs` option in an ini-file, for example your ``pytest.ini`` in the project root directory:
+You can set the :confval:`norecursedirs` option in a configuration file:
 
-.. code-block:: ini
+.. tab:: ini
 
-    # content of pytest.ini
-    [pytest]
-    norecursedirs = .svn _build tmp*
+    .. code-block:: ini
+
+        [pytest]
+        norecursedirs = .svn _build tmp*
 
 This would tell ``pytest`` to not recurse into typical subversion or sphinx-build directories or into any ``tmp`` prefixed directory.
 
@@ -108,14 +109,15 @@ the :confval:`python_files`, :confval:`python_classes` and
 :confval:`python_functions` in your :ref:`configuration file <config file formats>`.
 Here is an example:
 
-.. code-block:: ini
+.. tab:: ini
+
+    .. code-block:: ini
 
-    # content of pytest.ini
-    # Example 1: have pytest look for "check" instead of "test"
-    [pytest]
-    python_files = check_*.py
-    python_classes = Check
-    python_functions = *_check
+        # Example 1: have pytest look for "check" instead of "test"
+        [pytest]
+        python_files = check_*.py
+        python_classes = Check
+        python_functions = *_check
 
 This would make ``pytest`` look for tests in files that match the ``check_*
 .py`` glob-pattern, ``Check`` prefixes in classes, and functions and methods
@@ -152,12 +154,13 @@ The test collection would look like this:
 
 You can check for multiple glob patterns by adding a space between the patterns:
 
-.. code-block:: ini
+.. tab:: ini
+
+    .. code-block:: ini
 
-    # Example 2: have pytest look for files with "test" and "example"
-    # content of pytest.ini
-    [pytest]
-    python_files = test_*.py example_*.py
+        # Example 2: have pytest look for files with "test" and "example"
+        [pytest]
+        python_files = test_*.py example_*.py
 
 .. note::
 
@@ -178,14 +181,15 @@ example if you have unittest2 installed you can type:
     pytest --pyargs unittest2.test.test_skipping -q
 
 which would run the respective test module.  Like with
-other options, through an ini-file and the :confval:`addopts` option you
+other options, through a configuration file and the :confval:`addopts` option you
 can make this change more permanently:
 
-.. code-block:: ini
+.. tab:: ini
 
-    # content of pytest.ini
-    [pytest]
-    addopts = --pyargs
+    .. code-block:: ini
+
+        [pytest]
+        addopts = --pyargs
 
 Now a simple invocation of ``pytest NAME`` will check
 if NAME exists as an importable package/module and otherwise
@@ -224,11 +228,12 @@ Customizing test collection
 
 You can easily instruct ``pytest`` to discover tests from every Python file:
 
-.. code-block:: ini
+.. tab:: ini
+
+    .. code-block:: ini
 
-    # content of pytest.ini
-    [pytest]
-    python_files = *.py
+        [pytest]
+        python_files = *.py
 
 However, many projects will have a ``setup.py`` which they don't want to be
 imported. Moreover, there may files only importable by a specific python

doc/en/example/simple.rst

@@ -11,11 +11,12 @@ every time you use ``pytest``.  For example, if you always want to see
 detailed info on skipped and xfailed tests, as well as have terser "dot"
 progress output, you can write it into a configuration file:
 
-.. code-block:: ini
+.. tab:: ini
 
-    # content of pytest.ini
-    [pytest]
-    addopts = -ra -q
+    .. code-block:: ini
+
+        [pytest]
+        addopts = -ra -q
 
 
 Alternatively, you can set a ``PYTEST_ADDOPTS`` environment variable to add command
@@ -29,7 +30,7 @@ Here's how the command-line is built in the presence of ``addopts`` or the envir
 
 .. code-block:: text
 
-    <pytest.ini:addopts> $PYTEST_ADDOPTS <extra command-line arguments>
+    <configuration file addopts> $PYTEST_ADDOPTS <extra command-line arguments>
 
 So if the user executes in the command-line:
 

doc/en/explanation/goodpractices.rst

@@ -94,14 +94,14 @@ This has the following benefits:
 
 For new projects, we recommend to use ``importlib`` :ref:`import mode <import-modes>`
 (see which-import-mode_ for a detailed explanation).
-To this end, add the following to your ``pyproject.toml``:
+To this end, add the following to your configuration file:
 
-.. code-block:: toml
+.. tab:: ini
+
+    .. code-block:: ini
 
-    [tool.pytest.ini_options]
-    addopts = [
-        "--import-mode=importlib",
-    ]
+        [pytest]
+        addopts = --import-mode=importlib
 
 .. _src-layout:
 
@@ -126,12 +126,14 @@ which are better explained in this excellent `blog post`_ by Ionel Cristian Măr
        PYTHONPATH=src pytest
 
     or in a permanent manner by using the :confval:`pythonpath` configuration variable and adding the
-    following to your ``pyproject.toml``:
+    following to your configuration file:
+
+    .. tab:: ini
 
-    .. code-block:: toml
+        .. code-block:: ini
 
-        [tool.pytest.ini_options]
-        pythonpath = "src"
+            [pytest]
+            pythonpath = src
 
 .. note::
 

doc/en/how-to/capture-warnings.rst

@@ -80,30 +80,20 @@ as an error:
     FAILED test_show_warnings.py::test_one - UserWarning: api v1, should use ...
     1 failed in 0.12s
 
-The same option can be set in the ``pytest.ini`` or ``pyproject.toml`` file using the
-``filterwarnings`` ini option. For example, the configuration below will ignore all
+The same option can be set in the configuration file using the
+:confval:`filterwarnings` configuration option. For example, the configuration below will ignore all
 user warnings and specific deprecation warnings matching a regex, but will transform
 all other warnings into errors.
 
-.. code-block:: ini
+.. tab:: ini
 
-    # pytest.ini
-    [pytest]
-    filterwarnings =
-        error
-        ignore::UserWarning
-        ignore:function ham\(\) is deprecated:DeprecationWarning
-
-.. code-block:: toml
+    .. code-block:: ini
 
-    # pyproject.toml
-    [tool.pytest.ini_options]
-    filterwarnings = [
-        "error",
-        "ignore::UserWarning",
-        # note the use of single quote below to denote "raw" strings in TOML
-        'ignore:function ham\(\) is deprecated:DeprecationWarning',
-    ]
+        [pytest]
+        filterwarnings =
+            error
+            ignore::UserWarning
+            ignore:function ham\(\) is deprecated:DeprecationWarning
 
 
 When a warning matches more than one option in the list, the action for the last matching option
@@ -112,7 +102,7 @@ is performed.
 
 .. note::
 
-    The ``-W`` flag and the ``filterwarnings`` ini option use warning filters that are
+    The ``-W`` flag and the :confval:`filterwarnings` configuration option use warning filters that are
     similar in structure, but each configuration option interprets its filter
     differently. For example, *message* in ``filterwarnings`` is a string containing a
     regular expression that the start of the warning message must match,
@@ -169,7 +159,7 @@ You can specify multiple filters with separate decorators:
 
 
 Filters applied using a mark take precedence over filters passed on the command line or configured
-by the :confval:`filterwarnings` ini option.
+by the :confval:`filterwarnings` configuration option.
 
 You may apply a filter to all tests of a class by using the :ref:`filterwarnings <pytest.mark.filterwarnings ref>` mark as a class
 decorator or to all tests in a module by setting the :globalvar:`pytestmark` variable:
@@ -202,7 +192,9 @@ warning summary entirely from the test run output.
 Disabling warning capture entirely
 ----------------------------------
 
-This plugin is enabled by default but can be disabled entirely in your ``pytest.ini`` file with:
+This plugin is enabled by default but can be disabled entirely in your configuration file with:
+
+.. tab:: ini
 
     .. code-block:: ini
 
@@ -227,16 +219,18 @@ However, in the specific case where users capture any type of warnings in their
 no warning will be displayed at all.
 
 Sometimes it is useful to hide some specific deprecation warnings that happen in code that you have no control over
-(such as third-party libraries), in which case you might use the warning filters options (ini or marks) to ignore
+(such as third-party libraries), in which case you might use the warning filters options (configuration or marks) to ignore
 those warnings.
 
 For example:
 
-.. code-block:: ini
+.. tab:: ini
 
-    [pytest]
-    filterwarnings =
-        ignore:.*U.*mode is deprecated:DeprecationWarning
+    .. code-block:: ini
+
+        [pytest]
+        filterwarnings =
+            ignore:.*U.*mode is deprecated:DeprecationWarning
 
 
 This will ignore all warnings of type ``DeprecationWarning`` where the start of the message matches

doc/en/how-to/doctest.rst

@@ -68,27 +68,29 @@ and functions, including from test modules:
     ============================ 2 passed in 0.12s =============================
 
 You can make these changes permanent in your project by
-putting them into a pytest.ini file like this:
+putting them into a configuration file like this:
 
-.. code-block:: ini
+.. tab:: ini
 
-    # content of pytest.ini
-    [pytest]
-    addopts = --doctest-modules
+    .. code-block:: ini
+
+        [pytest]
+        addopts = --doctest-modules
 
 
 Encoding
 --------
 
 The default encoding is **UTF-8**, but you can specify the encoding
 that will be used for those doctest files using the
-``doctest_encoding`` ini option:
+:confval:`doctest_encoding` configuration option:
+
+.. tab:: ini
 
-.. code-block:: ini
+    .. code-block:: ini
 
-    # content of pytest.ini
-    [pytest]
-    doctest_encoding = latin1
+        [pytest]
+        doctest_encoding = latin1
 
 .. _using doctest options:
 
@@ -102,10 +104,12 @@ configuration file.
 For example, to make pytest ignore trailing whitespaces and ignore
 lengthy exception stack traces you can just write:
 
-.. code-block:: ini
+.. tab:: ini
+
+    .. code-block:: ini
 
-    [pytest]
-    doctest_optionflags = NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL
+        [pytest]
+        doctest_optionflags = NORMALIZE_WHITESPACE IGNORE_EXCEPTION_DETAIL
 
 Alternatively, options can be enabled by an inline comment in the doc test
 itself:

doc/en/how-to/fixtures.rst

@@ -1736,13 +1736,14 @@ and you may specify fixture usage at the test module level using :globalvar:`pyt
 
 
 It is also possible to put fixtures required by all tests in your project
-into an ini-file:
+into a configuration file:
 
-.. code-block:: ini
+.. tab:: ini
 
-    # content of pytest.ini
-    [pytest]
-    usefixtures = cleandir
+    .. code-block:: ini
+
+        [pytest]
+        usefixtures = cleandir
 
 
 .. warning::