Add dedicated CLI options reference documentation

[FazeelUsmani]

Problem

Currently, pytest's command-line options are only documented in the pytest --help output. While comprehensive, this format has limitations:

• Not easily searchable - Users must scan through the entire help text
• Not browsable online - Help text isn't part of the web documentation
• Difficult to discover - Users may not know what options exist for their use case
• Hard to reference - Can't easily link to specific options in discussions or other docs

This addresses the long-standing issue #4492 which requests CLI usage documentation be added to the online docs.

Proposed Solution

Add a dedicated "CLI Options Reference" page in the documentation (doc/en/how-to/cli-options.rst) that:

1. Organizes options by category for easier navigation:

   • Running and Selecting Tests
   • Output and Verbosity
   • Debugging and Profiling
   • Logging
   • Coverage and Reporting
   • Warnings
   • Fixtures
   • Caching
   • Configuration

2. Provides context and examples for commonly-used options

3. Cross-references to related comprehensive documentation sections

4. Makes options discoverable through the searchable online docs

Example Structure

Running and Selecting Tests
----------------------------

-k EXPRESSION
    Only run tests matching the given expression
    See: :ref:`mark examples`

-x, --exitfirst
    Exit instantly on first error or failed test

Implementation Approach

Rather than auto-generating docs with sphinx-argparse (as suggested in #4492), I propose a manually curated reference that:

• Focuses on commonly-used options
• Provides helpful context and usage examples
• Organizes logically by use case
• Links to detailed documentation where applicable

Trade-offs:

• ✅ More user-friendly and contextual
• ✅ Better organized for learning
• ❌ Requires manual maintenance to stay in sync

Related

• Addresses Missing docs for CLI usage #4492
• Draft implementation available at PR Add CLI options reference documentation #13930

[bluetech]

Thanks for opening the issue. I think this is a desirable thing to have in general. The following are my comments, assuming that the other devs also agree that we should have something like this.

Auto-generated or manual?

The first decision is whether it should be auto-generated using something like sphinx-argparse or maintained manually like you suggest.

In my opinion an auto-generated solution will have lower quality, because --help output needs to be short and can't use RST syntax etc. It would be nice to be able to expand more in the docs.

However, it does add maintenance overhead, and we might forget about it. Though that's not so bad I guess. We already deal with it for configuration values.

Place in the docs

This should be put in doc/en/reference/reference.rst, not in a separate file. Similar to configuration options.

Completeness

You suggest "Focuses on commonly-used options", I think we should document all options, otherwise it's not really a reference.

References

It would be good to be able to reference a flag in the docs, like we do with configuration values using e.g. :confval:`strict`. So we should register a custom object type in sphinx, maybe optionval following parser.addoption? Dunno which name to use...

Plugins

We should make clear at the beginning of the reference that external plugins may add their own CLI flags, and this documents only the flags from core plugin.

Embedded help output

The API reference currently contains an embedded copy of the --help output (using regendoc probably). I figure we can keep it, but maybe in a detail/summary sort of thing.

Environment variables

Unrelated to this issue, but it would be cool to have this for pytest envvars as well as a follow up.

[FazeelUsmani]

Thanks for the detailed feedback! I've implemented all your suggestions:

1. Manual curation ✓
   Used manual documentation (not auto-generated) so we can provide expanded descriptions, RST formatting,
   examples, and cross-references.
2. Location ✓
   Moved to doc/en/reference/reference.rst in the existing Command-line Flags section, not a separate file.
3. Completeness ✓
   Now documents all CLI options from core pytest, not just commonly-used ones.
4. Cross-referencing ✓
   Implemented custom :optionval: Sphinx directive in conf.py (following the same pattern as :confval:). Can
   now reference flags like :optionval:--pdb` throughout the docs.
5. Plugin flags ✓
   Added a note at the beginning clarifying that external plugins may add their own flags and this documents
   only core pytest options.
6. Embedded help output ✓
   Kept the complete pytest --help output under a "Complete Help Output" subsection.

The options are organized into categories (Test Selection, Test Execution Control, Collection, Fixtures,
Debugging, Output and Reporting, Logging, Configuration, etc.) with detailed descriptions and examples for
each.

The changes are ready for review. Would appreciate any feedback!