Add CLI options reference documentation

[FazeelUsmani]

Addresses #13973

Summary

Previously, pytest command-line options were only visible via pytest --help, making them difficult to discover and browse online. This PR adds a dedicated CLI options reference page to improve discoverability and provide a better documentation experience.

Changes

Added a new documentation page (doc/en/how-to/cli-options.rst) that organizes commonly used pytest CLI options into logical categories:

• Running and Selecting Tests (-k, -m, -x, --maxfail, --lf, --ff, --sw)
• Output and Verbosity (-v, -q, --tb, -l, -r)
• Reporting and Output Files (--junit-xml, --durations, -s)
• Collection and Test Discovery (--collect-only, --pyargs, --ignore)
• Debugging (--pdb, --trace, --fixtures, --setup-show)
• Configuration (-c, --basetemp, -o)
• Logging (--log-cli-level, --log-level, --log-file)
• Warnings (--disable-warnings, -W)
• Common Option Combinations for typical workflows

Each section includes clear examples, brief explanations, and cross-references to related documentation. The page also links to the complete command-line flag reference for users who need the exhaustive list.

Files Changed

• Added doc/en/how-to/cli-options.rst - new CLI options reference page (307 lines)
• Updated doc/en/how-to/index.rst - added the new page to the table of contents
• Added changelog/4492.doc.rst - changelog entry

Testing

The documentation was successfully built using Sphinx with no errors. All cross-references are valid and the generated HTML renders correctly.

[bluetech]

Hi @FazeelUsmani, can you open an issue with your proposal? It will allow us to have a place to discuss the idea not in the context of a specific PR.

[FazeelUsmani]

Sure, let me open

[bluetech]

Thanks for the update!

Quick preview link: https://pytest--13930.org.readthedocs.build/en/13930/reference/reference.html#command-line-flags

Please see my comment below.

---

When a flag has short and long (or alternatives) it is rendered as:

First, I think it would be nicer to render the alternatives in a single line, separated by commas. It makes it clearer they are alternatives, and not just something that we forgot to document.

Second, I think we should only have one canonical optionval per set of alternatives, probably the long spelling. I don't think we should have multiple ways to reference an option.

---

I think some of the options can have better links to places in the docs which discuss them, but I realize this is hard work, so not a blocker, maybe can be improved in the future.

---

Another thing we can improve in the future is to go over the docs and when a flag is mentioned make it a hyperlink using optionval. Also hard work, not a blocker for this PR.

---

The optionval reference should only include the flag name, not the value, e.g. in .. optionval:: --ignore-glob=path the path should not be included, otherwise it's unnatural to reference it.

Also, I think it would be better if the optionval also didn't include the --. If we standardize on only using the long spelling (when available) as the canonical then it should not be ambiguous. So in the example above, would reference using :optionval:`ignore-glob` and render as --ignore-blob. Well actually maybe it's better to keep the --. Happy to hear opinions...

[nicoddemus]

So in the example above, would reference using :optionval:ignore-glob and render as --ignore-blob. Well actually maybe it's better to keep the --. Happy to hear opinions...

I'm OK with either, TBH.

[FazeelUsmani]

@nicoddemus Done ✅

[bluetech]

I updated the PR:

• Tweaked the changelog.
• Turns out Sphinx already has an object/directive for command line options :option:, changed to use that.

When I have time I will add more cross refs, then it should be good to go.

[nicoddemus]

Looks great, thanks @FazeelUsmani and @bluetech!

[bluetech]

I added some cross-refs and back-refs. Will merge once CI passes.

[nicoddemus]

I think we can backport this.

[patchback]

Backport to 9.0.x: 💚 backport PR created

✅ Backport PR branch: patchback/backports/9.0.x/922b60377a38238b282c062e9589fdbe7eac1804/pr-13930

Backported as #14013

🤖 @patchback
I'm built with octomachinery and
my source is open — https://github.com/sanitizers/patchback-github-app.