[PR #13930/922b6037 backport][9.0.x] Add CLI options reference documentation

changelog/4492.doc.rst

@@ -0,0 +1 @@
+The API Reference now contains cross-reference-able documentation of :ref:`pytest's command-line flags <command-line-flags>`.

doc/en/backwards-compatibility.rst

@@ -60,7 +60,7 @@ Keeping backwards compatibility has a very high priority in the pytest project.
 
 With the pytest 3.0 release, we introduced a clear communication scheme for when we will actually remove the old busted joint and politely ask you to use the new hotness instead, while giving you enough time to adjust your tests or raise concerns if there are valid reasons to keep deprecated functionality around.
 
-To communicate changes, we issue deprecation warnings using a custom warning hierarchy (see :ref:`internal-warnings`). These warnings may be suppressed using the standard means: ``-W`` command-line flag or ``filterwarnings`` ini options (see :ref:`warnings`), but we suggest to use these sparingly and temporarily, and heed the warnings when possible.
+To communicate changes, we issue deprecation warnings using a custom warning hierarchy (see :ref:`internal-warnings`). These warnings may be suppressed using the standard means: :option:`-W` command-line flag or :confval:`filterwarnings` configuration option (see :ref:`warnings`), but we suggest to use these sparingly and temporarily, and heed the warnings when possible.
 
 We will only start the removal of deprecated functionality in major releases (e.g. if we deprecate something in 3.0, we will start to remove it in 4.0), and keep it around for at least two minor releases (e.g. if we deprecate something in 3.9 and 4.0 is the next release, we start to remove it in 5.0, not in 4.0).
 

doc/en/builtin.rst

@@ -12,7 +12,7 @@ For information on plugin hooks and objects, see :ref:`plugins`.
 
 For information on the ``pytest.mark`` mechanism, see :ref:`mark`.
 
-For information about fixtures, see :ref:`fixtures`. To see a complete list of available fixtures (add ``-v`` to also see fixtures with leading ``_``), type :
+For information about fixtures, see :ref:`fixtures`. To see a complete list of available fixtures (add :option:`-v` to also see fixtures with leading ``_``), type :
 
 .. code-block:: pytest
 
@@ -53,15 +53,15 @@ For information about fixtures, see :ref:`fixtures`. To see a complete list of a
 
     capteesys -- .../_pytest/capture.py:1028
         Enable simultaneous text capturing and pass-through of writes
-        to ``sys.stdout`` and ``sys.stderr`` as defined by ``--capture=``.
+        to ``sys.stdout`` and ``sys.stderr`` as defined by :option:`--capture`.
 
 
         The captured output is made available via ``capteesys.readouterr()`` method
         calls, which return a ``(out, err)`` namedtuple.
         ``out`` and ``err`` will be ``text`` objects.
 
         The output is also passed-through, allowing it to be "live-printed",
-        reported, or both as defined by ``--capture=``.
+        reported, or both as defined by :option:`--capture`.
 
         Returns an instance of :class:`CaptureFixture[str] <pytest.CaptureFixture>`.
 

doc/en/example/markers.rst

@@ -167,9 +167,9 @@ Using ``-k expr`` to select tests based on their name
 
 .. versionadded:: 2.0/2.3.4
 
-You can use the ``-k`` command line option to specify an expression
+You can use the :option:`-k` command line option to specify an expression
 which implements a substring match on the test names instead of the
-exact match on markers that ``-m`` provides.  This makes it easy to
+exact match on markers that :option:`-m` provides.  This makes it easy to
 select tests based on their names:
 
 .. versionchanged:: 5.4
@@ -225,7 +225,7 @@ Or to select "http" and "quick" tests:
 You can use ``and``, ``or``, ``not`` and parentheses.
 
 
-In addition to the test's name, ``-k`` also matches the names of the test's parents (usually, the name of the file and class it's in),
+In addition to the test's name, :option:`-k` also matches the names of the test's parents (usually, the name of the file and class it's in),
 attributes set on the test function, markers applied to it or its parents and any :attr:`extra keywords <_pytest.nodes.Node.extra_keyword_matches>`
 explicitly added to it or its parents.
 
@@ -440,7 +440,7 @@ and here is one that specifies exactly the environment needed:
 
     ============================ 1 passed in 0.12s =============================
 
-The ``--markers`` option always gives you a list of available markers:
+The :option:`--markers` option always gives you a list of available markers:
 
 .. code-block:: pytest
 
@@ -658,7 +658,7 @@ Automatically adding markers based on test names
 
 If you have a test suite where test function names indicate a certain
 type of test, you can implement a hook that automatically defines
-markers so that you can use the ``-m`` option with it. Let's look
+markers so that you can use the :option:`-m` option with it. Let's look
 at this test module:
 
 .. code-block:: python

doc/en/example/parametrize.rst

@@ -83,9 +83,9 @@ Different options for test IDs
 ------------------------------------
 
 pytest will build a string that is the test ID for each set of values in a
-parametrized test. These IDs can be used with ``-k`` to select specific cases
+parametrized test. These IDs can be used with :option:`-k` to select specific cases
 to run, and they will also identify the specific case when one is failing.
-Running pytest with ``--collect-only`` will show the generated IDs.
+Running pytest with :option:`--collect-only` will show the generated IDs.
 
 Numbers, strings, booleans and None will have their usual string representation
 used in the test ID. For other objects, pytest will make a string based on

doc/en/example/pythoncollection.rst

@@ -5,7 +5,7 @@ Ignore paths during test collection
 -----------------------------------
 
 You can easily ignore certain test directories and modules during collection
-by passing the ``--ignore=path`` option on the cli. ``pytest`` allows multiple
+by passing the :option:`--ignore=path` option on the cli. ``pytest`` allows multiple
 ``--ignore`` options. Example:
 
 .. code-block:: text
@@ -43,16 +43,16 @@ you will see that ``pytest`` only collects test-modules, which do not match the
 
     ========================= 5 passed in 0.02 seconds =========================
 
-The ``--ignore-glob`` option allows to ignore test file paths based on Unix shell-style wildcards.
-If you want to exclude test-modules that end with ``_01.py``, execute ``pytest`` with ``--ignore-glob='*_01.py'``.
+The :option:`--ignore-glob` option allows to ignore test file paths based on Unix shell-style wildcards.
+If you want to exclude test-modules that end with ``_01.py``, execute ``pytest`` with :option:`--ignore-glob='*_01.py'`.
 
 Deselect tests during test collection
 -------------------------------------
 
-Tests can individually be deselected during collection by passing the ``--deselect=item`` option.
+Tests can individually be deselected during collection by passing the :option:`--deselect=item` option.
 For example, say ``tests/foobar/test_foobar_01.py`` contains ``test_a`` and ``test_b``.
 You can run all of the tests within ``tests/`` *except* for ``tests/foobar/test_foobar_01.py::test_a``
-by invoking ``pytest`` with ``--deselect tests/foobar/test_foobar_01.py::test_a``.
+by invoking ``pytest`` with ``--deselect=tests/foobar/test_foobar_01.py::test_a``.
 ``pytest`` allows multiple ``--deselect`` options.
 
 .. _duplicate-paths:
@@ -73,7 +73,7 @@ Example:
 
 Just collect tests once.
 
-To collect duplicate tests, use the ``--keep-duplicates`` option on the cli.
+To collect duplicate tests, use the :option:`--keep-duplicates` option on the cli.
 Example:
 
 .. code-block:: pytest
@@ -168,7 +168,7 @@ You can check for multiple glob patterns by adding a space between the patterns:
 Interpreting cmdline arguments as Python packages
 -----------------------------------------------------
 
-You can use the ``--pyargs`` option to make ``pytest`` try
+You can use the :option:`--pyargs` option to make ``pytest`` try
 interpreting arguments as python package names, deriving
 their file system path and then running the test. For
 example if you have unittest2 installed you can type:

doc/en/example/simple.rst

@@ -43,7 +43,7 @@ The actual command line executed is:
     pytest -ra -q -v -m slow
 
 Note that as usual for other command-line applications, in case of conflicting options the last one wins, so the example
-above will show verbose output because ``-v`` overwrites ``-q``.
+above will show verbose output because :option:`-v` overwrites :option:`-q`.
 
 
 .. _request example:
@@ -353,7 +353,7 @@ Example:
 
 The ``__tracebackhide__`` setting influences ``pytest`` showing
 of tracebacks: the ``checkconfig`` function will not be shown
-unless the ``--full-trace`` command line option is specified.
+unless the :option:`--full-trace` command line option is specified.
 Let's run our little function:
 
 .. code-block:: pytest
@@ -998,7 +998,7 @@ information.
 
 
 Sometimes a test session might get stuck and there might be no easy way to figure out
-which test got stuck, for example if pytest was run in quiet mode (``-q``) or you don't have access to the console
+which test got stuck, for example if pytest was run in quiet mode (:option:`-q`) or you don't have access to the console
 output. This is particularly a problem if the problem happens only sporadically, the famous "flaky" kind of tests.
 
 ``pytest`` sets the :envvar:`PYTEST_CURRENT_TEST` environment variable when running tests, which can be inspected

doc/en/explanation/goodpractices.rst

@@ -170,7 +170,7 @@ want to distribute them along with your application:
             test_view.py
             ...
 
-In this scheme, it is easy to run your tests using the ``--pyargs`` option:
+In this scheme, it is easy to run your tests using the :option:`--pyargs` option:
 
 .. code-block:: bash
 
@@ -217,7 +217,7 @@ Note that this layout also works in conjunction with the ``src`` layout mentione
     from each other and thus deriving a canonical import name helps
     to avoid surprises such as a test module getting imported twice.
 
-    With ``--import-mode=importlib`` things are less convoluted because
+    With :option:`--import-mode=importlib` things are less convoluted because
     pytest doesn't need to change ``sys.path``, making things much less
     surprising.
 

doc/en/explanation/pythonpath.rst

@@ -11,7 +11,7 @@ Import modes
 pytest as a testing framework needs to import test modules and ``conftest.py`` files for execution.
 
 Importing files in Python is a non-trivial process, so aspects of the
-import process can be controlled through the ``--import-mode`` command-line flag, which can assume
+import process can be controlled through the :option:`--import-mode` command-line flag, which can assume
 these values:
 
 .. _`import-mode-prepend`:
@@ -44,7 +44,7 @@ these values:
         pkg_under_test/
 
   the tests will run against the installed version
-  of ``pkg_under_test`` when ``--import-mode=append`` is used whereas
+  of ``pkg_under_test`` when :option:`--import-mode=append` is used whereas
   with ``prepend``, they would pick up the local version. This kind of confusion is why
   we advocate for using :ref:`src-layouts <src-layout>`.
 

doc/en/getting-started.rst

@@ -262,7 +262,7 @@ Find out what kind of builtin :ref:`pytest fixtures <fixtures>` exist with the c
 
     pytest --fixtures   # shows builtin and custom fixtures
 
-Note that this command omits fixtures with leading ``_`` unless the ``-v`` option is added.
+Note that this command omits fixtures with leading ``_`` unless the :option:`-v` option is added.
 
 Continue reading
 -------------------------------------

doc/en/how-to/assert.rst

@@ -599,4 +599,4 @@ If this is the case you have two options:
 * Disable rewriting for a specific module by adding the string
   ``PYTEST_DONT_REWRITE`` to its docstring.
 
-* Disable rewriting for all modules by using ``--assert=plain``.
+* Disable rewriting for all modules by using :option:`--assert=plain`.

doc/en/how-to/cache.rst

@@ -13,11 +13,11 @@ Usage
 The plugin provides two command line options to rerun failures from the
 last ``pytest`` invocation:
 
-* ``--lf``, ``--last-failed`` - to only re-run the failures.
-* ``--ff``, ``--failed-first`` - to run the failures first and then the rest of
+* :option:`--lf, --last-failed <--lf>` - to only re-run the failures.
+* :option:`--ff, --failed-first <--ff>` - to run the failures first and then the rest of
   the tests.
 
-For cleanup (usually not needed), a ``--cache-clear`` option allows to remove
+For cleanup (usually not needed), a :option:`--cache-clear` option allows to remove
 all cross-session cache contents ahead of a test run.
 
 Other plugins may access the `config.cache`_ object to set/get
@@ -80,7 +80,7 @@ If you run this for the first time you will see two failures:
     FAILED test_50.py::test_num[25] - Failed: bad luck
     2 failed, 48 passed in 0.12s
 
-If you then run it with ``--lf``:
+If you then run it with :option:`--lf`:
 
 .. code-block:: pytest
 
@@ -124,7 +124,7 @@ If you then run it with ``--lf``:
 You have run only the two failing tests from the last run, while the 48 passing
 tests have not been run ("deselected").
 
-Now, if you run with the ``--ff`` option, all tests will be run but the first
+Now, if you run with the :option:`--ff` option, all tests will be run but the first
 previous failures will be executed first (as can be seen from the series
 of ``FF`` and dots):
 
@@ -169,14 +169,14 @@ of ``FF`` and dots):
 
 .. _`config.cache`:
 
-New ``--nf``, ``--new-first`` options: run new tests first followed by the rest
+New :option:`--nf, --new-first <--nf>` option: run new tests first followed by the rest
 of the tests, in both cases tests are also sorted by the file modified time,
 with more recent files coming first.
 
 Behavior when no tests failed in the last run
 ---------------------------------------------
 
-The ``--lfnf/--last-failed-no-failures`` option governs the behavior of ``--last-failed``.
+The :option:`--lfnf, --last-failed-no-failures <--lfnf>` option governs the behavior of :option:`--last-failed`.
 Determines whether to execute tests when there are no previously (known)
 failures or when no cached ``lastfailed`` data was found.
 
@@ -275,7 +275,7 @@ Inspecting Cache content
 ------------------------
 
 You can always peek at the content of the cache using the
-``--cache-show`` command line option:
+:option:`--cache-show` command line option:
 
 .. code-block:: pytest
 
@@ -294,7 +294,7 @@ You can always peek at the content of the cache using the
 
     ========================== no tests ran in 0.12s ===========================
 
-``--cache-show`` takes an optional argument to specify a glob pattern for
+:option:`--cache-show` takes an optional argument to specify a glob pattern for
 filtering:
 
 .. code-block:: pytest
@@ -314,7 +314,7 @@ Clearing Cache content
 ----------------------
 
 You can instruct pytest to clear all cache files and values
-by adding the ``--cache-clear`` option like this:
+by adding the :option:`--cache-clear` option like this:
 
 .. code-block:: bash
 
@@ -330,4 +330,4 @@ than speed.
 Stepwise
 --------
 
-As an alternative to ``--lf -x``, especially for cases where you expect a large part of the test suite will fail, ``--sw``, ``--stepwise`` allows you to fix them one at a time. The test suite will run until the first failure and then stop. At the next invocation, tests will continue from the last failing test and then run until the next failing test. You may use the ``--stepwise-skip`` option to ignore one failing test and stop the test execution on the second failing test instead. This is useful if you get stuck on a failing test and just want to ignore it until later.  Providing ``--stepwise-skip`` will also enable ``--stepwise`` implicitly.
+As an alternative to :option:`--lf` :option:`-x`, especially for cases where you expect a large part of the test suite will fail, :option:`--sw, --stepwise <--sw>` allows you to fix them one at a time. The test suite will run until the first failure and then stop. At the next invocation, tests will continue from the last failing test and then run until the next failing test. You may use the :option:`--stepwise-skip` option to ignore one failing test and stop the test execution on the second failing test instead. This is useful if you get stuck on a failing test and just want to ignore it until later.  Providing ``--stepwise-skip`` will also enable ``--stepwise`` implicitly.

doc/en/how-to/capture-stdout-stderr.rst

@@ -4,19 +4,19 @@
 How to capture stdout/stderr output
 =========================================================
 
-Pytest intercepts stdout and stderr as configured by the ``--capture=``
+Pytest intercepts stdout and stderr as configured by the :option:`--capture=`
 command-line argument or by using fixtures. The ``--capture=`` flag configures
 reporting, whereas the fixtures offer more granular control and allows
 inspection of output during testing. The reports can be customized with the
-`-r flag <../reference/reference.html#command-line-flags>`_.
+:option:`-r` flag.
 
 Default stdout/stderr/stdin capturing behaviour
 ---------------------------------------------------------
 
 During test execution any output sent to ``stdout`` and ``stderr`` is
 captured.  If a test or a setup method fails its according captured
-output will usually be shown along with the failure traceback. (this
-behavior can be configured by the ``--show-capture`` command-line option).
+output will usually be shown along with the failure traceback. (This
+behavior can be configured by the :option:`--show-capture` command-line option).
 
 In addition, ``stdin`` is set to a "null" object which will
 fail on attempts to read from it because it is rarely desired

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

@@ -198,7 +198,7 @@ decorator or to all tests in a module by setting the :globalvar:`pytestmark` var
 Disabling warnings summary
 --------------------------
 
-Although not recommended, you can use the ``--disable-warnings`` command-line option to suppress the
+Although not recommended, you can use the :option:`--disable-warnings` command-line option to suppress the
 warning summary entirely from the test run output.
 
 Disabling warning capture entirely

doc/en/how-to/doctest.rst

@@ -11,7 +11,7 @@ can change the pattern by issuing:
 
     pytest --doctest-glob="*.rst"
 
-on the command line. ``--doctest-glob`` can be given multiple times in the command-line.
+on the command line. :option:`--doctest-glob` can be given multiple times in the command-line.
 
 If you then have a text file like this:
 
@@ -39,7 +39,7 @@ then you can just invoke ``pytest`` directly:
     ============================ 1 passed in 0.12s =============================
 
 By default, pytest will collect ``test*.txt`` files looking for doctest directives, but you
-can pass additional globs using the ``--doctest-glob`` option (multi-allowed).
+can pass additional globs using the :option:`--doctest-glob` option (multi-allowed).
 
 In addition to text files, you can also execute doctests directly from docstrings of your classes
 and functions, including from test modules:

doc/en/how-to/failures.rst

@@ -93,8 +93,8 @@ Pytest supports the use of ``breakpoint()`` with the following behaviours:
 
  - When ``breakpoint()`` is called and ``PYTHONBREAKPOINT`` is set to the default value, pytest will use the custom internal PDB trace UI instead of the system default ``Pdb``.
  - When tests are complete, the system will default back to the system ``Pdb`` trace UI.
- - With ``--pdb`` passed to pytest, the custom internal Pdb trace UI is used with both ``breakpoint()`` and failed tests/unhandled exceptions.
- - ``--pdbcls`` can be used to specify a custom debugger class.
+ - With :option:`--pdb` passed to pytest, the custom internal Pdb trace UI is used with both ``breakpoint()`` and failed tests/unhandled exceptions.
+ - :option:`--pdbcls` can be used to specify a custom debugger class.
 
 
 .. _faulthandler:

doc/en/how-to/fixtures.rst

@@ -1368,9 +1368,9 @@ different server string is expected than what arrived.
 pytest will build a string that is the test ID for each fixture value
 in a parametrized fixture, e.g. ``test_ehlo[smtp.gmail.com]`` and
 ``test_ehlo[mail.python.org]`` in the above examples.  These IDs can
-be used with ``-k`` to select specific cases to run, and they will
+be used with :option:`-k` to select specific cases to run, and they will
 also identify the specific case when one is failing.  Running pytest
-with ``--collect-only`` will show the generated IDs.
+with :option:`--collect-only` will show the generated IDs.
 
 Numbers, strings, booleans and ``None`` will have their usual string
 representation used in the test ID. For other objects, pytest will