Skip to content

doc: fix ~75 typos and grammar issues across documentation#14179

Merged
nicoddemus merged 3 commits intopytest-dev:mainfrom
him2him2:fix-docs-typos-grammar
Feb 11, 2026
Merged

doc: fix ~75 typos and grammar issues across documentation#14179
nicoddemus merged 3 commits intopytest-dev:mainfrom
him2him2:fix-docs-typos-grammar

Conversation

@him2him2
Copy link
Contributor

Summary

Fix ~75 typos and grammar issues across 37 documentation files, covering how-to guides, reference docs, examples, explanations, changelog, and project root files.

Categories of fixes

  • Broken RST directives: .. note:.. note:: (missing colon breaks rendering)
  • Subject-verb agreement: "suites handles" → "suites handle", "provide" → "provides", etc.
  • Missing/incorrect articles: "In relatively large" → "In a relatively large", etc.
  • Incorrect prepositions: "compatible to" → "compatible with", "referencing to" → "referencing"
  • Wrong verb forms: "teared down" → "torn down", "lead to" → "led to", "convert" → "converting"
  • Duplicate/extra words: "to to do" → "to do", "daily at our daily" → "daily in our", extra spaces
  • Spelling errors: "termal" → "terminal", "specially" → "especially", "straight forward" → "straightforward"
  • Incorrect possessives: "It's functionality" → "Its functionality"
  • Wrong URL: changelog entry 13963 referenced pytest-dev/pytest instead of pytest-dev/pytest-xdist
  • Ordinal typo: "March 3th" → "March 3rd"
  • Other grammar: "allows to capture" → "allows capturing", "an warning" → "a warning"

Files changed

37 files across:

  • Project root: CONTRIBUTING.rst, RELEASING.rst
  • doc/en/: index.rst, deprecations.rst, backwards-compatibility.rst, historical-notes.rst, funcarg_compare.rst, sponsor.rst
  • doc/en/how-to/: assert.rst, cache.rst, capture-stdout-stderr.rst, capture-warnings.rst, doctest.rst, fixtures.rst, logging.rst, monkeypatch.rst, output.rst, skipping.rst, subtests.rst, writing_hook_functions.rst, writing_plugins.rst
  • doc/en/reference/: customize.rst, exit-codes.rst, fixtures.rst, reference.rst
  • doc/en/explanation/: ci.rst, flaky.rst, goodpractices.rst
  • doc/en/example/: attic.rst, customdirectory.rst, markers.rst, parametrize.rst, pythoncollection.rst, simple.rst
  • changelog/: README.rst, 12444.bugfix.rst, 13963.bugfix.rst

Notes

  • Auto-generated code output blocks (from regendoc) were intentionally left untouched
  • CODE_OF_CONDUCT.md was excluded as it uses the standard Contributor Covenant v1.4 template text

@psf-chronographer psf-chronographer bot added the bot:chronographer:provided (automation) changelog entry is part of PR label Feb 11, 2026
Fix typos, grammar errors, and broken RST directives found across
37 documentation files including how-to guides, reference docs,
examples, explanations, and project root files.

Notable fixes:
- Broken RST directives (``.. note:`` → ``.. note::``)
- Subject-verb agreement errors
- Missing/incorrect articles and prepositions
- Incorrect verb forms ("teared down" → "torn down")
- Duplicate words and extra spaces
- Wrong URL in changelog (pytest → pytest-xdist)
- Ordinal typo ("3th" → "3rd")
@him2him2 him2him2 force-pushed the fix-docs-typos-grammar branch from d330859 to 46c0adc Compare February 11, 2026 07:30
@@ -1,3 +1,3 @@
Fixed subtests running with `pytest-xdist <https://github.com/pytest-dev/pytest>`__ when their contexts contain objects that are not JSON-serializable.
Fixed subtests running with `pytest-xdist <https://github.com/pytest-dev/pytest-xdist>`__ when their contexts contain objects that are not JSON-serializable.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Or we could just link the PyPI project page:

Suggested change
Fixed subtests running with `pytest-xdist <https://github.com/pytest-dev/pytest-xdist>`__ when their contexts contain objects that are not JSON-serializable.
Fixed subtests running with :pypi:`pytest-xdist` when their contexts contain objects that are not JSON-serializable.

@@ -0,0 +1 @@
Fixed ~75 typos and grammar issues across documentation, including broken RST directives, subject-verb agreement errors, missing articles, and incorrect prepositions.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure if this note is actually needed in the change log.

@webknjaz
Copy link
Member

@him2him2 please reveal the tooling used / how you automated this.

in our example from a `conftest plugin`_.

sidenote: the temporary directory used here are instances of
sidenote: the temporary directories used here are instances of
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Does sidenote need fixing too?

* ``improvement``: improvement of existing functionality, usually without requiring user intervention (for example, new fields being written in ``--junit-xml``, improved colors in terminal, etc).
* ``bugfix``: fixes a bug.
* ``doc``: documentation improvement, like rewording an entire session or adding missing docs.
* ``doc``: documentation improvement, like rewording an entire section or adding missing docs.
Copy link
Member

@webknjaz webknjaz Feb 11, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

self note: 🤔 this might need to be updated in pip-tools / aio-libs / cheroot / ansible-pylibssh

The goal of testing in a CI pipeline is different from testing locally. Indeed,
you can quickly edit some code and run your tests again on your computer, but
it is not possible with CI pipeline. They run on a separate server and are
it is not possible with a CI pipeline. It runs on a separate server and is
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this might've been meant as plural in that sentence:

Suggested change
it is not possible with a CI pipeline. It runs on a separate server and is
it is not possible with CI pipelines. They run on a separate server and are

Plus this variant would make the patch more surgical.

.. note::

If you do not use an editable install and not use the ``src`` layout (``mypkg`` directly in the root
If you do not use an editable install and do not use the ``src`` layout (``mypkg`` directly in the root
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe not directly related but it's probably a good idea to reference https://packaging.python.org/en/latest/discussions/src-layout-vs-flat-layout/. Though, this is likely something to do in a follow-up.

raise ExceptionGroup("", (ValueError("foo")))

They both supply a method :meth:`pytest.RaisesGroup.matches` :meth:`pytest.RaisesExc.matches` if you want to do matching outside of using it as a contextmanager. This can be helpful when checking ``.__context__`` or ``.__cause__``.
They both supply a method :meth:`pytest.RaisesGroup.matches` :meth:`pytest.RaisesExc.matches` if you want to do matching outside of using it as a context manager. This can be helpful when checking ``.__context__`` or ``.__cause__``.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This seems like a good time to reference the term docs:

Suggested change
They both supply a method :meth:`pytest.RaisesGroup.matches` :meth:`pytest.RaisesExc.matches` if you want to do matching outside of using it as a context manager. This can be helpful when checking ``.__context__`` or ``.__cause__``.
They both supply a method :meth:`pytest.RaisesGroup.matches` :meth:`pytest.RaisesExc.matches` if you want to do matching outside of using it as a :external+python:std:ref:`context manager <context-managers>`. This can be helpful when checking ``.__context__`` or ``.__cause__``.

addopts = -p no:warnings

Or passing ``-p no:warnings`` in the command-line. This might be useful if your test suites handles warnings
Or passing ``-p no:warnings`` in the command-line. This might be useful if your test suites handle warnings
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think you misjudged the original intent here:

Suggested change
Or passing ``-p no:warnings`` in the command-line. This might be useful if your test suites handle warnings
Or passing ``-p no:warnings`` in the command-line. This might be useful if your test suite handles warnings

@@ -217,7 +217,7 @@ option names are:

If you need to record the whole test suite logging calls to a file, you can pass
:option:`--log-file=/path/to/log/file`. This log file is opened in write mode by default which
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We probably need a comma here, right?

Suggested change
:option:`--log-file=/path/to/log/file`. This log file is opened in write mode by default which
:option:`--log-file=/path/to/log/file`. This log file is opened in write mode by default, which

If you need to record the whole test suite logging calls to a file, you can pass
:option:`--log-file=/path/to/log/file`. This log file is opened in write mode by default which
means that it will be overwritten at each run tests session.
means that it will be overwritten at each test run session.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I have a feeling that this was meant to be

Suggested change
means that it will be overwritten at each test run session.
means that it will be overwritten at each test session.

Need additional opinions, though.

def test_function(): ...

This is specially useful for xfailing tests that are crashing the interpreter and should be
This is especially useful for xfailing tests that are crashing the interpreter and should be
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I feel like the intent was

Suggested change
This is especially useful for xfailing tests that are crashing the interpreter and should be
This is particularly useful for xfailing tests that are crashing the interpreter and should be

Opinions?

.. note::

If you would like to customize the exit code in some scenarios, specially when
If you would like to customize the exit code in some scenarios, especially when
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It looks like the author might've wanted to say

Suggested change
If you would like to customize the exit code in some scenarios, especially when
If you would like to customize the exit code in some scenarios, specifically when

Right?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Tip

Note for other reviewers: the changes here do indeed fix the admonitions — they were previously parsed as RST comments and not displayed at all. Now they are rendered as visual blocks. See:
https://pytest--14179.org.readthedocs.build/en/14179/reference/fixtures.html#autouse-fixtures-are-executed-first-within-their-scope vs. https://docs.pytest.org/en/latest/reference/fixtures.html#autouse-fixtures-are-executed-first-within-their-scope (scroll to the bottom)

.. envvar:: CI

When set to a non-empty value, pytest acknowledges that is running in a CI process. See also :ref:`ci-pipelines`.
When set to a non-empty value, pytest acknowledges that it is running in a CI process. See also :ref:`ci-pipelines`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should these descriptions be indented?

.. option:: --log-file=PATH

Path to a file when logging will be written to.
Path to a file where logging will be written to.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should it even be there?

Suggested change
Path to a file where logging will be written to.
Path to a file logging will be written to.

``pytest.yield_fixture`` is a deprecated alias for :func:`pytest.fixture`.

It has been so for a very long time, so can be search/replaced safely.
It has been so for a very long time, so it can be search/replaced safely.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
It has been so for a very long time, so it can be search/replaced safely.
It has been so for a very long time, so it can be searched/replaced safely.

parser.

The `pytest-reportlog <https://github.com/pytest-dev/pytest-reportlog>`__ plugin provides a ``--report-log`` option, a more standard and extensible alternative, producing
The `pytest-reportlog <https://github.com/pytest-dev/pytest-reportlog>`__ plugin provides a ``--report-log`` option, a more standard and extensible alternative, producing
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
The `pytest-reportlog <https://github.com/pytest-dev/pytest-reportlog>`__ plugin provides a ``--report-log`` option, a more standard and extensible alternative, producing
The :pypi:`pytest-reportlog` plugin provides a ``--report-log`` option, a more standard and extensible alternative, producing

.. sidebar:: **Next Open Trainings and Events**

- `Professional Testing with Python <https://python-academy.com/courses/python_course_testing.html>`_, via `Python Academy <https://www.python-academy.com/>`_ (3 day in-depth training), **March 3th -- 5th 2026**, Remote
- `Professional Testing with Python <https://python-academy.com/courses/python_course_testing.html>`_, via `Python Academy <https://www.python-academy.com/>`_ (3 day in-depth training), **March 3rd -- 5th 2026**, Remote
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I wonder if we could have a custom RST directive for events/trainings that would normalize dates and such.

RELEASING.rst Outdated
#. Create a branch ``release-MAJOR.MINOR.PATCH`` from the ``MAJOR.MINOR.x`` branch.

Ensure your are updated and in a clean working tree.
Ensure you are updated and in a clean working tree.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be rephrased further.

CONTRIBUTING.rst Outdated
~~~~~~~~~~~~~~~~~~~~~

When closing a Pull Request, it needs to be acknowledging the time, effort, and interest demonstrated by the person which submitted it. As mentioned previously, it is not the intent of the team to dismiss a stalled pull request entirely but to merely to clear up our queue, so a message like the one below is warranted when closing a pull request that went stale:
When closing a Pull Request, it needs to acknowledge the time, effort, and interest demonstrated by the person who submitted it. As mentioned previously, it is not the intent of the team to dismiss a stalled pull request entirely but to merely to clear up our queue, so a message like the one below is warranted when closing a pull request that went stale:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
When closing a Pull Request, it needs to acknowledge the time, effort, and interest demonstrated by the person who submitted it. As mentioned previously, it is not the intent of the team to dismiss a stalled pull request entirely but to merely to clear up our queue, so a message like the one below is warranted when closing a pull request that went stale:
When closing a Pull Request, we should acknowledge the time, effort, and interest demonstrated by the person who submitted it. As mentioned previously, it is not the intent of the team to dismiss a stalled pull request entirely but to merely to clear up our queue, so a message like the one below is warranted when closing a pull request that went stale:

CONTRIBUTING.rst Outdated
~~~~~~~~~~~~~

Here are a few general rules the maintainers use deciding when to close issues/PRs because
Here are a few general rules the maintainers use when deciding when to close issues/PRs because
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This double-when doesn't seem organic. Let's rethink it.

@him2him2
Copy link
Contributor Author

@him2him2 please reveal the tooling used / how you automated this.

I used Claude Code Opus 4.6 to help find the issues. Then personally read all the suggested changes before submitting the PR.

@webknjaz
Copy link
Member

@him2him2 please reveal the tooling used / how you automated this.

I used Claude Code Opus 4.6 to help find the issues. Then personally read all the suggested changes before submitting the PR.

Thanks! This is useful to know. In the future, I recommend you exposing this in the PR description.

Tip

@him2him2 another contribution you might be interested in would be exploring if and how we could integrate https://vale.sh into the CI/linting infra, as a standalone/follow-up PR.

Apply suggestions from PR review:
- changelog/13963.bugfix.rst: use :pypi: role instead of raw URL
- changelog/14205.doc.rst: remove unnecessary changelog entry
- doc/en/example/attic.rst: "sidenote" → "Side note"
- doc/en/explanation/ci.rst: keep plural "CI pipelines. They run...are"
- doc/en/how-to/assert.rst: cross-reference "context manager" to Python docs
- doc/en/how-to/capture-warnings.rst: singular "test suite handles"
- doc/en/how-to/logging.rst: add missing comma, "each test session"
- doc/en/how-to/skipping.rst: "particularly" instead of "especially"
- doc/en/reference/exit-codes.rst: "specifically" instead of "especially"
- doc/en/reference/reference.rst: drop "where" from log-file description
- doc/en/deprecations.rst: "searched/replaced", use :pypi: role
- RELEASING.rst: rephrase "Ensure your local checkout is up to date"
- CONTRIBUTING.rst: "we should acknowledge", fix double-when, add backport label
@webknjaz
Copy link
Member

I've marked 21 out of 38 files as reviewed and left comments in some others. This will need another maintainer's review, some suggestions invite discussion and may be incomplete or controversial. Signing off for now.

- changelog/12444.bugfix.rst: link Mapping class with :class: role
- doc/en/explanation/ci.rst: link CI and BUILD_NUMBER with :envvar: role
@webknjaz
Copy link
Member

I've marked 21 out of 38 files as reviewed and left comments in some others.

Now bumped to 34/37.

@webknjaz
Copy link
Member

@him2him2 I recommend accepting suggested patches on GH UI (easier and more correct authorship tracking). Also, this is useful to know: https://hynek.me/til/easier-crediting-contributors-github/.

@webknjaz webknjaz added skip news used on prs to opt out of the changelog requirement and removed bot:chronographer:provided (automation) changelog entry is part of PR labels Feb 11, 2026
@him2him2
Copy link
Contributor Author

Thank you @webknjaz for the thorough and thoughtful review — all of your suggested changes have been applied across two follow-up commits.

A couple of notes:

  • The Changelog entry check is now failing since we removed changelog/14205.doc.rst per your feedback. Let me know if a label or other action is needed to address that.
  • I've noted the two items you flagged as potential follow-ups (envvar description indentation in reference.rst, and the packaging.python.org link in goodpractices.rst) — happy to tackle those in a separate PR if helpful.
  • Thank you for the tip about accepting suggested patches via the GitHub UI for proper authorship tracking — I'll use that approach going forward.

@webknjaz
Copy link
Member

  • The Changelog entry check is now failing since we removed changelog/14205.doc.rst per your feedback. Let me know if a label or other action is needed to address that.

I did that already, you're good.

him2him2 added a commit to him2him2/pytest that referenced this pull request Feb 11, 2026
Indent the body text of all ``.. envvar::`` entries in ``reference.rst``
to match the 3-space indentation convention used by ``.. confval::``
entries in the same file.

Add a ``.. seealso::`` link to the packaging.python.org src-layout vs
flat-layout discussion in ``goodpractices.rst``.

Follow-up to pytest-dev#14179.
@webknjaz webknjaz added the type: docs documentation improvement, missing or needing clarification label Feb 11, 2026
Copy link
Member

@nicoddemus nicoddemus left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @him2him2 for the PR and @webknjaz for the thorough review. 👍

@nicoddemus nicoddemus added the backport 9.0.x apply to PRs at any point; backports the changes to the 9.0.x branch label Feb 11, 2026
@nicoddemus nicoddemus merged commit b2310f2 into pytest-dev:main Feb 11, 2026
33 checks passed
@patchback
Copy link

patchback bot commented Feb 11, 2026

Backport to 9.0.x: 💔 cherry-picking failed — conflicts found

❌ Failed to cleanly apply b2310f2 on top of patchback/backports/9.0.x/b2310f28314249e4bfa1e0b9817dbef5cb968f4d/pr-14179

Backporting merged PR #14179 into main

  1. Ensure you have a local repo clone of your fork. Unless you cloned it
    from the upstream, this would be your origin remote.
  2. Make sure you have an upstream repo added as a remote too. In these
    instructions you'll refer to it by the name upstream. If you don't
    have it, here's how you can add it:
    $ git remote add upstream https://github.com/pytest-dev/pytest.git
  3. Ensure you have the latest copy of upstream and prepare a branch
    that will hold the backported code:
    $ git fetch upstream
    $ git checkout -b patchback/backports/9.0.x/b2310f28314249e4bfa1e0b9817dbef5cb968f4d/pr-14179 upstream/9.0.x
  4. Now, cherry-pick PR doc: fix ~75 typos and grammar issues across documentation #14179 contents into that branch:
    $ git cherry-pick -x b2310f28314249e4bfa1e0b9817dbef5cb968f4d
    If it'll yell at you with something like fatal: Commit b2310f28314249e4bfa1e0b9817dbef5cb968f4d is a merge but no -m option was given., add -m 1 as follows instead:
    $ git cherry-pick -m1 -x b2310f28314249e4bfa1e0b9817dbef5cb968f4d
  5. At this point, you'll probably encounter some merge conflicts. You must
    resolve them in to preserve the patch from PR doc: fix ~75 typos and grammar issues across documentation #14179 as close to the
    original as possible.
  6. Push this branch to your fork on GitHub:
    $ git push origin patchback/backports/9.0.x/b2310f28314249e4bfa1e0b9817dbef5cb968f4d/pr-14179
  7. Create a PR, ensure that the CI is green. If it's not — update it so that
    the tests and any other checks pass. This is it!
    Now relax and wait for the maintainers to process your pull request
    when they have some cycles to do reviews. Don't worry — they'll tell you if
    any improvements are necessary when the time comes!

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

@webknjaz
Copy link
Member

@him2him2 could you follow the instructions in the bot comment above to create a backport pull request?

him2him2 added a commit to him2him2/pytest that referenced this pull request Feb 11, 2026
…v#14179)

Fix typos, grammar errors, and broken RST directives found across 37 documentation files including how-to guides, reference docs, examples, explanations, and project root files.

Notable fixes:
- Broken RST directives (``.. note:`` → ``.. note::``)
- Subject-verb agreement errors
- Missing/incorrect articles and prepositions
- Incorrect verb forms ("teared down" → "torn down")
- Duplicate words and extra spaces
- Wrong URL in changelog (pytest → pytest-xdist)
- Ordinal typo ("3th" → "3rd")

(cherry picked from commit b2310f2)
@him2him2
Copy link
Contributor Author

@webknjaz Done — backport PR created: #14185

Three conflicts were resolved:

  • changelog/13963.bugfix.rst: removed (already consumed into a release on 9.0.x)
  • doc/en/deprecations.rst: dropped fixes to config.inicfg and parametrize-iterators sections which don't exist on 9.0.x
  • doc/en/how-to/fixtures.rst: kept the grammar fixes

webknjaz added a commit that referenced this pull request Feb 11, 2026
doc: backport typo and grammar fixes to 9.0.x (from #14179)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backport 9.0.x apply to PRs at any point; backports the changes to the 9.0.x branch skip news used on prs to opt out of the changelog requirement type: docs documentation improvement, missing or needing clarification

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

Comments