doc: fix ~75 typos and grammar issues across documentation#14179
doc: fix ~75 typos and grammar issues across documentation#14179nicoddemus merged 3 commits intopytest-dev:mainfrom
Conversation
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")
d330859 to
46c0adc
Compare
changelog/13963.bugfix.rst
Outdated
| @@ -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. | |||
There was a problem hiding this comment.
Or we could just link the PyPI project page:
| 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. |
changelog/14205.doc.rst
Outdated
| @@ -0,0 +1 @@ | |||
| Fixed ~75 typos and grammar issues across documentation, including broken RST directives, subject-verb agreement errors, missing articles, and incorrect prepositions. | |||
There was a problem hiding this comment.
Not sure if this note is actually needed in the change log.
|
@him2him2 please reveal the tooling used / how you automated this. |
doc/en/example/attic.rst
Outdated
| 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 |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
self note: 🤔 this might need to be updated in pip-tools / aio-libs / cheroot / ansible-pylibssh
doc/en/explanation/ci.rst
Outdated
| 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 |
There was a problem hiding this comment.
I think this might've been meant as plural in that sentence:
| 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 |
There was a problem hiding this comment.
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.
doc/en/how-to/assert.rst
Outdated
| 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__``. |
There was a problem hiding this comment.
This seems like a good time to reference the term docs:
| 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__``. |
doc/en/how-to/capture-warnings.rst
Outdated
| 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 |
There was a problem hiding this comment.
I think you misjudged the original intent here:
| 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 |
doc/en/how-to/logging.rst
Outdated
| @@ -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 | |||
There was a problem hiding this comment.
We probably need a comma here, right?
| :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 |
doc/en/how-to/logging.rst
Outdated
| 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. |
There was a problem hiding this comment.
I have a feeling that this was meant to be
| 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.
doc/en/how-to/skipping.rst
Outdated
| 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 |
There was a problem hiding this comment.
I feel like the intent was
| 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?
doc/en/reference/exit-codes.rst
Outdated
| .. 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 |
There was a problem hiding this comment.
It looks like the author might've wanted to say
| 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?
There was a problem hiding this comment.
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`. |
There was a problem hiding this comment.
Should these descriptions be indented?
doc/en/reference/reference.rst
Outdated
| .. option:: --log-file=PATH | ||
|
|
||
| Path to a file when logging will be written to. | ||
| Path to a file where logging will be written to. |
There was a problem hiding this comment.
Should it even be there?
| Path to a file where logging will be written to. | |
| Path to a file logging will be written to. |
doc/en/deprecations.rst
Outdated
| ``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. |
There was a problem hiding this comment.
| 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. |
doc/en/deprecations.rst
Outdated
| 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 |
There was a problem hiding this comment.
| 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 |
There was a problem hiding this comment.
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. |
There was a problem hiding this comment.
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: |
There was a problem hiding this comment.
| 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 |
There was a problem hiding this comment.
This double-when doesn't seem organic. Let's rethink it.
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
|
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
Now bumped to 34/37. |
|
@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/. |
|
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:
|
I did that already, you're good. |
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.
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
🤖 @patchback |
|
@him2him2 could you follow the instructions in the bot comment above to create a backport pull request? |
…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)
|
@webknjaz Done — backport PR created: #14185 Three conflicts were resolved:
|
doc: backport typo and grammar fixes to 9.0.x (from #14179)
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
.. note:→.. note::(missing colon breaks rendering)pytest-dev/pytestinstead ofpytest-dev/pytest-xdistFiles changed
37 files across:
CONTRIBUTING.rst,RELEASING.rstdoc/en/:index.rst,deprecations.rst,backwards-compatibility.rst,historical-notes.rst,funcarg_compare.rst,sponsor.rstdoc/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.rstdoc/en/reference/:customize.rst,exit-codes.rst,fixtures.rst,reference.rstdoc/en/explanation/:ci.rst,flaky.rst,goodpractices.rstdoc/en/example/:attic.rst,customdirectory.rst,markers.rst,parametrize.rst,pythoncollection.rst,simple.rstchangelog/:README.rst,12444.bugfix.rst,13963.bugfix.rstNotes
regendoc) were intentionally left untouchedCODE_OF_CONDUCT.mdwas excluded as it uses the standard Contributor Covenant v1.4 template text