Add CLI options reference documentation (#13930)

Co-authored-by: Ran Benita <[email protected]>

Author: FazeelUsmani

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