minor doc improvements (#2006)

Author: jugmac00

docs/changelog/2006.doc.rst

@@ -0,0 +1 @@
+Start polishing the documentation for the upcoming final release - by :user:`jugmac00`.

docs/development.rst

@@ -56,7 +56,7 @@ To run tests locally execute:
     tox -e py
 
 This will run the test suite for the same Python version as under which ``tox`` is installed. Alternatively you can
-specify a specific version of python by using the ``pyNN`` format, such as: ``py38``, ``pypy3``, etc.
+specify a specific version of Python by using the ``pyNN`` format, such as: ``py38``, ``pypy3``, etc.
 
 ``tox`` has been configured to forward any additional arguments it is given to ``pytest``.
 This enables the use of pytest's
@@ -71,14 +71,14 @@ select tests using the various ways that pytest provides:
     tox -e py -- -k "test_extra"
 
 Some tests require additional dependencies to be run, such is the various shell activators (``bash``, ``fish``,
-``powershell``, etc). These tests will automatically be skipped if these are not present, note however that in CI
+``powershell``, etc). The tests will be skipped automatically if the dependencies are not present. Please note however that in CI
 all tests are run; so even if all tests succeed locally for you, they may still fail in the CI.
 
 Running linters
 ~~~~~~~~~~~~~~~
 
 tox uses :pypi:`pre-commit` for managing linting of the codebase. ``pre-commit`` performs various checks on all
-files in tox and uses tools that help follow a consistent code style within the codebase. To use linters locally,
+files in tox and uses tools that help following a consistent code style within the codebase. To use linters locally,
 run:
 
 .. code-block:: shell
@@ -96,7 +96,7 @@ Code style guide
 
 - First and foremost, the linters configured for the project must pass; this generally means following PEP-8 rules,
   as codified by: ``flake8``, ``black``, ``isort``, ``pyupgrade``.
-- Packaging options should be specified within ``setup.cfg``, ``setup.py`` is only kept for editable installs.
+- Packaging options should be specified within ``setup.cfg``; ``setup.py`` is only kept for editable installs.
 - All code (tests too) must be type annotated as much as required by ``mypy``.
 - We use a line length of 120.
 - Exception messages should only be capitalized (and ended with a period/exclamation mark) if they are multi-sentenced,
@@ -132,13 +132,13 @@ Contributing
 Submitting pull requests
 ~~~~~~~~~~~~~~~~~~~~~~~~
 
-Submit pull requests against the ``master`` branch, providing a good description of what you're doing and why. You must
+Submit pull requests (PRs) against the ``master`` branch, providing a good description of what you're doing and why. You must
 have legal permission to distribute any code you contribute to tox and it must be available under the MIT
 License. Provide tests that cover your changes and run the tests locally first. tox
 :ref:`supports <compatibility-requirements>` multiple Python versions and operating systems. Any pull request must
 consider and work on all these platforms.
 
-Pull Requests should be small to facilitate review. Keep them self-contained, and limited in scope. `Studies have shown
+Pull requests should be small to facilitate review. Keep them self-contained, and limited in scope. `Studies have shown
 <https://www.kessler.de/prd/smartbear/BestPracticesForPeerCodeReview.pdf>`_ that review quality falls off as patch size
 grows. Sometimes this will result in many small PRs to land a single large feature. In particular, pull requests must
 not be treated as "feature branches", with ongoing development work happening within the PR. Instead, the feature should
@@ -151,22 +151,22 @@ or whitespace within lines. Such changes can be made separately, as a "formattin
 Automated testing
 ~~~~~~~~~~~~~~~~~
 
-All pull requests and merges to 'master' branch are tested using
-`Azure Pipelines <https://azure.microsoft.com/en-gb/services/devops/pipelines/>`_ (configured by
-``azure-pipelines.yml`` file at the root of the repository). You can find the status and results to the CI runs for your
+All pull requests and merges to the ``master`` branch are tested using
+`GitHub Actions <https://github.com/features/actions>`_ (configured by ``check.yml`` file inside the
+``.github/workflows`` directory). You can find the status and the results to the CI runs for your
 PR on GitHub's Web UI for the pull request. You can also find links to the CI services' pages for the specific builds in
 the form of "Details" links, in case the CI run fails and you wish to view the output.
 
 To trigger CI to run again for a pull request, you can close and open the pull request or submit another change to the
 pull request. If needed, project maintainers can manually trigger a restart of a job/build.
 
-NEWS entries
-~~~~~~~~~~~~
+Changelog entries
+~~~~~~~~~~~~~~~~~
 
-The ``changelog.rst`` file is managed using :pypi:`towncrier` and all non trivial changes must be accompanied by a news
-entry. To add an entry to the news file, first you need to have created an issue describing the change you want to
-make. A Pull Request itself *may* function as such, but it is preferred to have a dedicated issue (for example, in case
-the PR ends up rejected due to code quality reasons).
+The ``changelog.rst`` file is managed using :pypi:`towncrier` and all non trivial changes must be accompanied by a
+changelog entry. To add an entry to the changelog, first you need to have created an issue describing the
+change you want to make. A  pull request itself *may* function as such, but it is preferred to have a dedicated issue
+(for example, in case the PR ends up rejected due to code quality reasons).
 
 Once you have an issue or pull request, you take the number and you create a file inside of the ``docs/changelog``
 directory named after that issue number with an extension of:
@@ -183,27 +183,20 @@ added a feature and deprecated/removed the old feature at the same time, you wou
 ``docs/changelog/1234.bugfix.rst`` and ``docs/changelog/1234.remove.rst``). Likewise if a PR touches multiple issues/PRs
 you may create a file for each of them with the same contents and :pypi:`towncrier` will deduplicate them.
 
-Contents of a NEWS entry
-^^^^^^^^^^^^^^^^^^^^^^^^
+Contents of a changelog entry
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-The contents of this file are reStructuredText formatted text that will be used as the content of the news file entry.
+The content of this file is reStructuredText formatted text that will be used as the content of the changelog entry.
 You do not need to reference the issue or PR numbers here as towncrier will automatically add a reference to all of
-the affected issues when rendering the news file.
+the affected issues when rendering the changelog.
 
-In order to maintain a consistent style in the ``changelog.rst`` file, it is preferred to keep the news entry to the
+In order to maintain a consistent style in the ``changelog.rst`` file, it is preferred to keep the entries to the
 point, in sentence case, shorter than 120 characters and in an imperative tone -- an entry should complete the sentence
 ``This change will …``. In rare cases, where one line is not enough, use a summary line in an imperative tone followed
 by a blank line separating it from a description of the feature/change in one or more paragraphs, each wrapped
-at 120 characters. Remember that a news entry is meant for end users and should only contain details relevant to an end
-user.
-
-Choosing the type of NEWS entry
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+at 120 characters. Remember that a changelog entry is meant for end users and should only contain details relevant to an
+end user.
 
-A trivial change is anything that does not warrant an entry in the news file. Some examples are: code refactors that
-don't change anything as far as the public is concerned, typo fixes, white space modification, etc. To mark a PR
-as trivial a contributor simply needs to add a randomly named, empty file to the ``news/`` directory with the extension
-of ``.trivial``.
 
 Becoming a maintainer
 ~~~~~~~~~~~~~~~~~~~~~

docs/index.rst

@@ -37,7 +37,7 @@ and `devpi <https://devpi.net/>`_).
 tox is a generic virtual environment management and test command line tool you can use for:
 
 * checking your package builds and installs correctly under different environments (such as different Python
-  implementations, versions or install dependencies),
+  implementations, versions or installation dependencies),
 * running your tests in each of the environments with the test tool of choice,
 * acting as a frontend to Continuous Integration servers, greatly reducing boilerplate and merging CI and
   shell-based testing.

docs/installation.rst

@@ -4,8 +4,8 @@ Installation
 via pipx
 --------
 
-:pypi:`tox` is a CLI tool that needs a Python interpreter to run. The tool requires first to have ``Python 3.6+``
-interpreter the best is to use :pypi:`pipx` to install tox into an isolated environment. This has the added
+:pypi:`tox` is a CLI tool that needs a Python interpreter (version 3.6 or higher) to run.
+We recommend :pypi:`pipx` to install tox into an isolated environment. This has the added
 benefit that later you'll be able to upgrade tox without affecting other parts of the system.
 
 .. code-block:: console
@@ -17,7 +17,7 @@ via pip
 -------
 
 Alternatively you can install it within the global Python interpreter itself (perhaps as a user package via the
-``--user`` flag). Be cautious if you are using a python install that is managed by your operating system or
+``--user`` flag). Be cautious if you are using a Python installation that is managed by your operating system or
 another package manager. ``pip`` might not coordinate with those tools, and may leave your system in an
 inconsistent state. Note, if you go down this path you need to ensure pip is new enough per the subsections below:
 
@@ -29,8 +29,8 @@ inconsistent state. Note, if you go down this path you need to ensure pip is new
 wheel
 ~~~~~
 Installing tox via a wheel (default with pip) requires an installer that can understand the ``python-requires``
-tag (see `PEP-503 <https://www.python.org/dev/peps/pep-0503/>`_), with pip this is version ``9.0.0`` (released 2016
-November). Furthermore, in case you're not installing it via the PyPi you need to be using a mirror that correctly
+tag (see `PEP-503 <https://www.python.org/dev/peps/pep-0503/>`_), with pip this is version ``9.0.0`` (released in
+November 2016). Furthermore, in case you're not installing it via PyPi you need to use a mirror that correctly
 forwards the ``python-requires`` tag (notably the OpenStack mirrors don't do this, or older
 `devpi <https://github.com/devpi/devpi>`_ versions - added with version ``4.7.0``).
 
@@ -40,16 +40,16 @@ sdist
 ~~~~~
 When installing via a source distribution you need an installer that handles the
 `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`_ specification. In case of ``pip`` this is version ``18.0.0`` or
-later (released on 2018 July). If you cannot upgrade your pip to support this you need to ensure that the build
+later (released in July 2018). If you cannot upgrade your pip to support this you need to ensure that the build
 requirements from `pyproject.toml <https://github.com/tox-dev/tox/blob/master/pyproject.toml#L2>`_ are satisfied
-before triggering the install.
+before triggering the installation.
 
 via ``setup.py``
 ----------------
-We don't recommend and officially support this method. One should prefer using an installer that supports
+We don't recommend and officially support this method. You should prefer using an installer that supports
 `PEP-517 <https://www.python.org/dev/peps/pep-0517/>`_ interface, such as pip ``19.0.0`` or later. That being said you
-might be able to still install a package via this method if you satisfy build dependencies before calling the install
-command (as described under :ref:`sdist`).
+might be able to still install a package via this method if you satisfy build dependencies before calling the
+installation command (as described under :ref:`sdist`).
 
 latest unreleased
 -----------------

docs/plugins.rst

@@ -127,7 +127,7 @@ on how to migrate.
 
 ``tox_get_python_executable``
 -----------------------------
-With tox 4 the python discovery is performed ``tox.tox_env.python.virtual_env.api._get_python`` that delegates the job
+With tox 4 the Python discovery is performed ``tox.tox_env.python.virtual_env.api._get_python`` that delegates the job
 to ``virtualenv``. Therefore first `define a new virtualenv discovery mechanism
 <https://virtualenv.pypa.io/en/latest/extend.html#python-discovery>`_ and then set that by setting the
 ``VIRTUALENV_DISCOVERY`` environment variable.
@@ -136,6 +136,6 @@ to ``virtualenv``. Therefore first `define a new virtualenv discovery mechanism
 ---------------
 Register new packager types via :func:`tox_register_tox_env <tox.plugin.spec.tox_register_tox_env>`.
 
-``tox_addoption``
------------------
+``tox_adoption``
+----------------
 Renamed to :func:`tox_add_option <tox.plugin.spec.tox_add_option>`.

docs/user_guide.rst

@@ -2,13 +2,14 @@ User Guide
 ==========
 
 Basic example
------------------
+-------------
+
 Put basic information about your project and the test environments you want your project to run in into a ``tox.ini``
 file residing at the root of your project:
 
 .. code-block:: ini
 
-    # content of: tox.ini at the root of the project
+    # content of tox.ini at the root of the project
     [tox]
     envlist =
         py38
@@ -22,15 +23,15 @@ file residing at the root of your project:
         # NOTE: you can run any command line tool here - not just tests
         pytest
 
-You can also try generating a ``tox.ini`` file automatically, by running ``tox-quickstart`` and then answering a few
-simple questions. To sdist-package, install and test your project against Python3.7 and Python3.8, just type:
+You can also try generating a ``tox.ini`` file automatically by running ``tox quickstart`` and then answering a few
+simple questions. To sdist-package, install and test your project against Python3.7 and Python3.8, just type
 
 .. code-block:: console
 
     tox
 
-and watch things happening (you must have python3.7 and python3.8 installed in your environment otherwise you will see
-errors). When you run ``tox`` a second time you'll note that it runs much faster because it keeps track of virtualenv
+and watch things happening. You must have python3.7 and python3.8 installed in your environment, otherwise you will see
+errors. When you run ``tox`` a second time you'll notice that it runs much faster because it keeps track of virtualenv
 details and will not recreate or re-install dependencies.
 
 System overview
@@ -45,7 +46,7 @@ System overview
 tox roughly follows the following phases:
 
 1. **configuration:** load ``tox.ini`` and merge it with options from the command line and the operating system
-   environment variables.
+   environment variables
 2. **packaging** (optional): create a source distribution of the current project by invoking
 
    .. code-block:: bash
@@ -56,9 +57,9 @@ tox roughly follows the following phases:
    need to make sure that it contains your build dependencies). Skip this step for application projects that don't have
    a ``setup.py``.
 
-3. **environment** - for each tox environment (e.g. ``py37``, ``py38``) do:
+3. **environment**: for each tox environment (e.g. ``py37``, ``py38``) do:
 
-   1. **environment creation**: create a fresh environment, by default :pypi:`virtualenv` is used. tox will
+   1. **environment creation**: create a fresh environment; by default :pypi:`virtualenv` is used. tox will
    automatically try to discover a valid Python interpreter version by using the environment name (e.g. ``py37`` means
    Python 3.7 and the ``basepython`` configuration value) and the current operating system ``PATH`` value. This is
    created at first run only to be re-used at subsequent runs. If certain aspects of the project change, a re-creation
@@ -73,10 +74,9 @@ tox roughly follows the following phases:
    change.
 
    3. **commands**: run the specified commands in the specified order. Whenever the exit code of any of them is not
-   zero, stop and mark the environment failed. Note, starting a command with a single dash character means ignore exit
-   code.
+   zero, stop and mark the environment failed. When you start a command with a dash character, the exit code will be ignored.
 
-6. **report** print out a report of outcomes for each tox environment:
+4. **report** print out a report of outcomes for each tox environment:
 
    .. code:: bash
 
@@ -96,21 +96,21 @@ Current features
 ----------------
 
 * **automation of tedious Python related test activities**
-* **test your Python package against many interpreter and dependency configs**
+* **test your Python package against many interpreter and dependency configurations**
 
-    - automatic customizable (re)creation of :pypi:`virtualenv` test environments - installs your ``setup.py`` based
-      project into each virtual environment
-    - test-tool agnostic: runs pytest, nose or unittests in a uniform manner
+    - automatic customizable (re)creation of :pypi:`virtualenv` test environments
+    - installs your project into each virtual environment
+    - test-tool agnostic: runs pytest, nose or unittest in a uniform manner
 
 * ``plugin system`` to modify tox execution with simple hooks.
 * uses :pypi:`pip` and :pypi:`setuptools` by default. Support for configuring the installer command through
   ``install_command``.
-* **cross-Python compatible**: CPython-3.6 and higher, pypy 3.6+ and higher.
+* **cross-Python compatible**: CPython 3.6 and higher, pypy 3.6+ and higher.
 * **cross-platform**: Windows and Unix style environments
 * **integrates with continuous integration servers** like Jenkins (formerly known as Hudson) and helps you to avoid
-  boilerplatish and platform-specific build-step hacks.
+  boilerplatish and platform-specific build-step hacks
 * **full interoperability with devpi**: is integrated with and is used for testing in the :pypi:`devpi` system, a
-  versatile PyPI index server and release managing tool.
+  versatile PyPI index server and release managing tool
 * **driven by a simple ini-style config file**
 * **documented** examples and configuration
 * **concise reporting** about tool invocations and configuration errors

src/tox/plugin/spec.py

@@ -20,7 +20,7 @@ def _spec(func: _F) -> _F:
 @_spec
 def tox_register_tox_env(register: ToxEnvRegister) -> None:  # noqa: U100
     """
-    Register new tox environment type that. You can register:
+    Register new tox environment type. You can register:
 
     - **run environment**: by default this is a local subprocess backed virtualenv Python
     - **packaging environment**: by default this is a PEP-517 compliant local subprocess backed virtualenv Python

src/tox/session/cmd/quickstart.py

@@ -15,7 +15,7 @@ def tox_add_option(parser: ToxParser) -> None:
     our = parser.add_command(
         "quickstart",
         ["q"],
-        "Command-line script to quickly tox config file for a Python project",
+        "Command line script to quickly create a tox config file for a Python project",
         quickstart,
     )
     our.add_argument(

src/tox/session/cmd/run/common.py

@@ -63,7 +63,7 @@ def env_run_create_flags(parser: ArgumentParser, mode: str) -> None:
         metavar="path",
         of_type=Path,
         default=None,
-        help="write a json file with detailed information about all commands and results involved",
+        help="write a JSON file with detailed information about all commands and results involved",
     )
     if mode != "devenv":
         parser.add_argument(
@@ -101,7 +101,7 @@ def env_run_create_flags(parser: ArgumentParser, mode: str) -> None:
         parser.add_argument(
             "--develop",
             action="store_true",
-            help="install package in develop mode",
+            help="install package in development mode",
             dest="develop",
         )
     parser.add_argument(
@@ -118,7 +118,7 @@ def env_run_create_flags(parser: ArgumentParser, mode: str) -> None:
         dest="discover",
         nargs="+",
         metavar="path",
-        help="for python discovery first try the python executables under these paths",
+        help="for Python discovery first try the Python executables under these paths",
         default=[],
     )
     parser.add_argument(