doc: fix ~75 typos and grammar issues across documentation

CONTRIBUTING.rst

@@ -146,7 +146,7 @@ the following:
 - PyPI presence with packaging metadata that contains a ``pytest-``
   prefixed name, version number, authors, short and long description.
 
-- a  `tox configuration <https://tox.readthedocs.io/en/latest/config.html#configuration-discovery>`_
+- a `tox configuration <https://tox.readthedocs.io/en/latest/config.html#configuration-discovery>`_
   for running tests using `tox <https://tox.readthedocs.io>`_.
 
 - a ``README`` describing how to use the plugin and on which
@@ -280,7 +280,7 @@ Here is a simple overview, with pytest-specific bits:
 #. You can now edit your local working copy and run the tests again as necessary. Please follow `PEP-8 <https://www.python.org/dev/peps/pep-0008/>`_ for naming.
 
    You can pass different options to ``tox``. For example, to run tests on Python 3.13 and pass options to pytest
-   (e.g. enter pdb on failure) to pytest you can do::
+   (e.g. enter pdb on failure) you can do::
 
     $ tox -e py313 -- --pdb
 
@@ -346,7 +346,7 @@ For example, to ensure a simple test passes you can write:
         result.assert_outcomes(failed=0, passed=1)
 
 
-Alternatively, it is possible to make checks based on the actual output of the termal using
+Alternatively, it is possible to make checks based on the actual output of the terminal using
 *glob-like* expressions:
 
 .. code-block:: python
@@ -479,10 +479,10 @@ above?
    to do the backport.
 2. However, often the merge is done by another maintainer, in which case it is nice of them to
    do the backport procedure if they have the time.
-3. For bugs submitted by non-maintainers, it is expected that a core developer will to do
+3. For bugs submitted by non-maintainers, it is expected that a core developer will do
    the backport, normally the one that merged the PR on ``main``.
-4. If a non-maintainers notices a bug which is fixed on ``main`` but has not been backported
-   (due to maintainers forgetting to apply the *needs backport* label, or just plain missing it),
+4. If a non-maintainer notices a bug which is fixed on ``main`` but has not been backported
+   (due to maintainers forgetting to apply the *needs backport* or *backport x.x.x* labels, or just plain missing it),
    they are also welcome to open a PR with the backport. The procedure is simple and really
    helps with the maintenance of the project.
 
@@ -512,7 +512,7 @@ can always reopen the issue/pull request in their own time later if it makes sen
 When to close
 ~~~~~~~~~~~~~
 
-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 to decide when to close issues/PRs because
 of lack of inactivity:
 
 * Issues labeled ``question`` or ``needs information``: closed after 14 days inactive.
@@ -524,15 +524,15 @@ The above are **not hard rules**, but merely **guidelines**, and can be (and oft
 Closing pull requests
 ~~~~~~~~~~~~~~~~~~~~~
 
-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, 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:
 
     Hi <contributor>,
 
     First of all, we would like to thank you for your time and effort on working on this, the pytest team deeply appreciates it.
 
     We noticed it has been awhile since you have updated this PR, however. pytest is a high activity project, with many issues/PRs being opened daily, so it is hard for us maintainers to track which PRs are ready for merging, for review, or need more attention.
 
-    So for those reasons we, think it is best to close the PR for now, but with the only intention to clean up our queue, it is by no means a rejection of your changes. We still encourage you to re-open this PR (it is just a click of a button away) when you are ready to get back to it.
+    So for those reasons, we think it is best to close the PR for now, but with the only intention to clean up our queue, it is by no means a rejection of your changes. We still encourage you to re-open this PR (it is just a click of a button away) when you are ready to get back to it.
 
     Again we appreciate your time for working on this, and hope you might get back to this at a later time!
 

RELEASING.rst

@@ -117,7 +117,7 @@ To release a version ``MAJOR.MINOR.PATCH``, follow these steps:
 
 #. Create a branch ``release-MAJOR.MINOR.PATCH`` from the ``MAJOR.MINOR.x`` branch.
 
-   Ensure your are updated and in a clean working tree.
+   Ensure your local checkout is up to date and in a clean working tree.
 
 #. Using ``tox``, generate docs, changelog, announcements::
 

changelog/12444.bugfix.rst

@@ -1 +1 @@
-Fixed :func:`pytest.approx` which now correctly takes account Mapping keys order to compare them.
+Fixed :func:`pytest.approx` which now correctly takes into account :class:`~collections.abc.Mapping` keys order to compare them.

changelog/13963.bugfix.rst

@@ -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 :pypi:`pytest-xdist` when their contexts contain objects that are not JSON-serializable.
 
 Fixes `pytest-dev/pytest-xdist#1273 <https://github.com/pytest-dev/pytest-xdist/issues/1273>`__.

changelog/README.rst

@@ -16,12 +16,12 @@ Each file should be named like ``<ISSUE>.<TYPE>.rst``, where
 * ``feature``: new user facing features, like new command-line options and new behavior.
 * ``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.
 * ``deprecation``: feature deprecation.
 * ``breaking``: a change which may break existing suites, such as feature removal or behavior change.
 * ``vendor``: changes in packages vendored in pytest.
 * ``packaging``: notes for downstreams about unobvious side effects
-  and tooling. changes in the test invocation considerations and
+  and tooling. Changes in the test invocation considerations and
   runtime assumptions.
 * ``contrib``: stuff that affects the contributor experience. e.g.
   Running tests, building the docs, setting up the development

doc/en/backwards-compatibility.rst

@@ -53,8 +53,8 @@ History
 =========
 
 
-Focus primary on smooth transition - stance (pre 6.0)
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Focus primarily on smooth transition - stance (pre 6.0)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Keeping backwards compatibility has a very high priority in the pytest project. Although we have deprecated functionality over the years, most of it is still supported. All deprecations in pytest were done because simpler or more efficient ways of accomplishing the same tasks have emerged, making the old way of doing things unnecessary.
 

doc/en/deprecations.rst

@@ -90,7 +90,7 @@ Example of problematic code:
         def test_2(self, n):
             pass
 
-You can fix it by convert generators and iterators to lists or tuples:
+You can fix it by converting generators and iterators to lists or tuples:
 
 .. code-block:: python
 
@@ -167,7 +167,7 @@ In ``8.2`` the ``exc_type`` parameter has been added, giving users the ability o
 to skip tests only if the module cannot really be found, and not because of some other error.
 
 Catching only :class:`ModuleNotFoundError` by default (and letting other errors propagate) would be the best solution,
-however for backward compatibility, pytest will keep the existing behavior but raise an warning if:
+however for backward compatibility, pytest will keep the existing behavior but raise a warning if:
 
 1. The captured exception is of type :class:`ImportError`, and:
 2. The user does not pass ``exc_type`` explicitly.
@@ -342,7 +342,7 @@ The ``yield_fixture`` function/decorator
 
 ``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 searched/replaced safely.
 
 
 Removed Features and Breaking Changes
@@ -876,7 +876,7 @@ The ``pytest._fillfuncargs`` function
 
 This function was kept for backward compatibility with an older plugin.
 
-It's functionality is not meant to be used directly, but if you must replace
+Its functionality is not meant to be used directly, but if you must replace
 it, use `function._request._fillfixtures()` instead, though note this is not
 a public API and may break in the future.
 
@@ -907,7 +907,7 @@ The ``--result-log`` option produces a stream of test reports which can be
 analysed at runtime, but it uses a custom format which requires users to implement their own
 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 :pypi:`pytest-reportlog` plugin provides a ``--report-log`` option, a more standard and extensible alternative, producing
 one JSON object per-line, and should cover the same use cases. Please try it out and provide feedback.
 
 The ``pytest-reportlog`` plugin might even be merged into the core

doc/en/example/attic.rst

@@ -75,7 +75,7 @@ decorate its result.  This mechanism allows us to stay
 ignorant of how/where the function argument is provided -
 in our example from a `conftest plugin`_.
 
-sidenote: the temporary directory used here are instances of
+Side note: the temporary directories used here are instances of
 the `py.path.local`_ class which provides many of the os.path
 methods in a convenient way.
 

doc/en/example/customdirectory.rst

@@ -36,7 +36,7 @@ You can create a ``manifest.json`` file and some test files:
 .. include:: customdirectory/tests/test_third.py
     :literal:
 
-An you can now execute the test specification:
+And you can now execute the test specification:
 
 .. code-block:: pytest
 

doc/en/example/markers.rst

@@ -411,7 +411,7 @@ A test file using this local plugin:
     def test_basic_db_operation():
         pass
 
-and an example invocations specifying a different environment than what
+and an example invocation specifying a different environment than what
 the test needs:
 
 .. code-block:: pytest

doc/en/example/parametrize.rst

@@ -4,7 +4,7 @@
 Parametrizing tests
 =================================================
 
-``pytest`` allows to easily parametrize test functions.
+``pytest`` allows you to easily parametrize test functions.
 For basic docs, see :ref:`parametrize-basics`.
 
 In the following we provide some examples using
@@ -642,7 +642,7 @@ As the result:
 
 - Four tests were collected
 - One test was deselected because it doesn't have the ``basic`` mark.
-- Three tests with the ``basic`` mark was selected.
+- Three tests with the ``basic`` mark were selected.
 - The test ``test_eval[1+7-8]`` passed, but the name is autogenerated and confusing.
 - The test ``test_eval[basic_2+4]`` passed.
 - The test ``test_eval[basic_6*9]`` was expected to fail and did fail.

doc/en/example/pythoncollection.rst

@@ -161,7 +161,7 @@ You can check for multiple glob patterns by adding a space between the patterns:
 
 .. note::
 
-   the ``python_functions`` and ``python_classes`` options has no effect
+   the ``python_functions`` and ``python_classes`` options have no effect
    for ``unittest.TestCase`` test discovery because pytest delegates
    discovery of test case methods to unittest code.
 

doc/en/example/simple.rst

@@ -416,10 +416,10 @@ running from a test you can do this:
 
 
     if os.environ.get("PYTEST_VERSION") is not None:
-        # Things you want to to do if your code is called by pytest.
+        # Things you want to do if your code is called by pytest.
         ...
     else:
-        # Things you want to to do if your code is not called by pytest.
+        # Things you want to do if your code is not called by pytest.
         ...
 
 
@@ -773,7 +773,7 @@ The two test modules in the ``a`` directory see the same ``db`` fixture instance
 while the one test in the sister-directory ``b`` doesn't see it.  We could of course
 also define a ``db`` fixture in that sister directory's ``conftest.py`` file.
 Note that each fixture is only instantiated if there is a test actually needing
-it (unless you use "autouse" fixture which are always executed ahead of the first test
+it (unless you use "autouse" fixtures which are always executed ahead of the first test
 executing).
 
 

doc/en/explanation/ci.rst

@@ -8,7 +8,7 @@ Rationale
 
 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 CI pipelines. They run on a separate server and are
 triggered by specific actions.
 
 From that observation, pytest can detect when it is in a CI environment and
@@ -17,10 +17,10 @@ adapt some of its behaviours.
 How CI is detected
 ------------------
 
-Pytest knows it is in a CI environment when either one of these environment variables are set to a non-empty value:
+Pytest knows it is in a CI environment when either one of these environment variables is set to a non-empty value:
 
-* `CI`: used by many CI systems.
-* `BUILD_NUMBER`: used by Jenkins.
+* :envvar:`CI`: used by many CI systems.
+* :envvar:`BUILD_NUMBER`: used by Jenkins.
 
 Effects on CI
 -------------

doc/en/explanation/flaky.rst

@@ -42,7 +42,7 @@ It is of course possible (and common) for tests and fixtures to spawn threads th
 * Make sure to eventually wait on any spawned threads -- for example at the end of a test, or during the teardown of a fixture.
 * Avoid using primitives provided by pytest (:func:`pytest.warns`, :func:`pytest.raises`, etc) from multiple threads, as they are not thread-safe.
 
-If your test suite uses threads and your are seeing flaky test results, do not discount the possibility that the test is implicitly using global state in pytest itself.
+If your test suite uses threads and you are seeing flaky test results, do not discount the possibility that the test is implicitly using global state in pytest itself.
 
 Related features
 ^^^^^^^^^^^^^^^^

doc/en/explanation/goodpractices.rst

@@ -143,7 +143,7 @@ which are better explained in this excellent `blog post`_ by Ionel Cristian Măr
 
 .. 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
     directory) you can rely on the fact that Python by default puts the current directory in ``sys.path`` to
     import your package and run ``python -m pytest`` to execute the tests against the local copy directly.
 
@@ -376,7 +376,7 @@ If you don't want to automatically pick up new options, you can enable options i
         strict_parametrization_ids = true
         strict_xfail = true
 
-If you want to use strict mode but having trouble with a specific option, you can turn it off individually:
+If you want to use strict mode but are having trouble with a specific option, you can turn it off individually:
 
 .. tab:: toml
 

doc/en/funcarg_compare.rst

@@ -18,7 +18,7 @@ The pre pytest-2.3 funcarg mechanism calls a factory each time a
 funcarg for a test function is required.  If a factory wants to
 reuse a resource across different scopes, it often used
 the ``request.cached_setup()`` helper to manage caching of
-resources.  Here is a basic example how we could implement
+resources.  Here is a basic example of how we could implement
 a per-session Database object:
 
 .. code-block:: python
@@ -39,10 +39,10 @@ a per-session Database object:
 
 There are several limitations and difficulties with this approach:
 
-1. Scoping funcarg resource creation is not straight forward, instead one must
+1. Scoping funcarg resource creation is not straightforward, instead one must
    understand the intricate cached_setup() method mechanics.
 
-2. parametrizing the "db" resource is not straight forward:
+2. parametrizing the "db" resource is not straightforward:
    you need to apply a "parametrize" decorator or implement a
    :hook:`pytest_generate_tests` hook
    calling :py:func:`~pytest.Metafunc.parametrize` which
@@ -55,7 +55,7 @@ There are several limitations and difficulties with this approach:
    at the same time, making it hard for them to affect global state
    of the application under test.
 
-4. there is no way how you can make use of funcarg factories
+4. there is no way you can make use of funcarg factories
    in xUnit setup methods.
 
 5. A non-parametrized fixture function cannot use a parametrized

doc/en/historical-notes.rst

@@ -304,7 +304,7 @@ For more details see :ref:`breakpoints`.
 
 
 
-Access of ``Module``, ``Function``, ``Class``, ``Instance``, ``File`` and ``Item`` through ``Node`` instances have long
+Access of ``Module``, ``Function``, ``Class``, ``Instance``, ``File`` and ``Item`` through ``Node`` instances has long
 been documented as deprecated, but started to emit warnings from pytest ``3.9`` and onward.
 
 Users should just ``import pytest`` and access those objects using the ``pytest`` module.

doc/en/how-to/assert.rst

@@ -218,7 +218,7 @@ To specify more details about the contained exception you can use :class:`pytest
         with pytest.RaisesGroup(pytest.RaisesExc(ValueError, match="foo")):
             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 :external+python:std:ref:`context manager <context-managers>`. This can be helpful when checking ``.__context__`` or ``.__cause__``.
 
 .. code-block:: python
 

doc/en/how-to/cache.rst

@@ -33,7 +33,7 @@ Other plugins may access the `config.cache`_ object to set/get
 Rerunning only failures or failures first
 -----------------------------------------------
 
-First, let's create 50 test invocation of which only 2 fail:
+First, let's create 50 test invocations of which only 2 fail:
 
 .. code-block:: python
 

doc/en/how-to/capture-stdout-stderr.rst

@@ -6,7 +6,7 @@ How to capture stdout/stderr output
 
 Pytest intercepts stdout and stderr as configured by the :option:`--capture=`
 command-line argument or by using fixtures. The ``--capture=`` flag configures
-reporting, whereas the fixtures offer more granular control and allows
+reporting, whereas the fixtures offer more granular control and allow
 inspection of output during testing. The reports can be customized with the
 :option:`-r` flag.
 
@@ -23,7 +23,7 @@ fail on attempts to read from it because it is rarely desired
 to wait for interactive input when running automated tests.
 
 By default capturing is done by intercepting writes to low level
-file descriptors.  This allows to capture output from simple
+file descriptors.  This allows capturing output from simple
 print statements as well as output from a subprocess started by
 a test.
 

doc/en/how-to/capture-warnings.rst

@@ -220,7 +220,7 @@ This plugin is enabled by default but can be disabled entirely in your configura
         [pytest]
         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 suite handles warnings
 using an external system.
 
 

doc/en/how-to/doctest.rst

@@ -185,7 +185,7 @@ Output format
 -------------
 
 You can change the diff output format on failure for your doctests
-by using one of standard doctest modules format in options
+by using one of the standard doctest module's format options
 (see :data:`python:doctest.REPORT_UDIFF`, :data:`python:doctest.REPORT_CDIFF`,
 :data:`python:doctest.REPORT_NDIFF`, :data:`python:doctest.REPORT_ONLY_FIRST_FAILURE`):