diff --git a/docs/config.rst b/docs/config.rst index b80de22d3..1aec46a29 100644 --- a/docs/config.rst +++ b/docs/config.rst @@ -15,8 +15,8 @@ Out of box tox supports three configuration locations prioritized in the followi 2. ``pyproject.toml``, 3. ``setup.cfg``. -With regards to the configuration format, at the moment we only support *ini-style*. ``tox.ini`` and ``setup.cfg`` are by -nature such files, while in ``pyproject.toml`` currently you can only inline the *ini-style* config. +With regards to the configuration format, at the moment we only support *ini-style*. ``tox.ini`` and ``setup.cfg`` are +by nature such files, while in ``pyproject.toml`` currently you can only inline the *ini-style* config. Note that ``setup.cfg`` requires the content to be under the ``tox:tox`` and ``testenv`` sections and is otherwise ignored. ``pyproject.toml`` on the other hand is in TOML format. However, one can inline the *ini-style* format under @@ -616,8 +616,9 @@ Python run :keys: package :version_added: 4.0 - When option can be one of ``wheel``, ``sdist``, ``editable``, ``editable-legacy``, ``skip``, or ``external``. If :ref:`use_develop` is - set this becomes a constant of ``editable``. If :ref:`skip_install` is set this becomes a constant of ``skip``. + When option can be one of ``wheel``, ``sdist``, ``editable``, ``editable-legacy``, ``skip``, or ``external``. If + :ref:`use_develop` is set this becomes a constant of ``editable``. If :ref:`skip_install` is set this becomes a + constant of ``skip``. .. conf:: @@ -767,8 +768,8 @@ Pip installer :version_added: 2.4 The ``list_dependencies_command`` setting is used for listing the packages installed into the virtual environment. - This command will be executed only if executing on Contionous Integrations is detected (for example set environment variable ``CI=1``) - or if journal is active. + This command will be executed only if executing on Continuous Integrations is detected (for example set environment + variable ``CI=1``) or if journal is active. .. conf:: @@ -786,7 +787,7 @@ Pip installer :version_added: 4.4.0 If ``constrain_package_deps`` is true, then tox will create and use ``{env_dir}{/}constraints.txt`` when installing - package dependnecies during ``install_package_deps`` stage. When this value is set to false, any conflicting package + package dependencies during ``install_package_deps`` stage. When this value is set to false, any conflicting package dependencies will override explicit dependencies and constraints passed to ``deps``. .. conf:: @@ -795,17 +796,16 @@ Pip installer :version_added: 4.4.0 When ``use_frozen_constraints`` is true, then tox will use the ``list_dependencies_command`` to enumerate package - versions in order to create ``{env_dir}{/}constraints.txt``. Otherwise the package specifications explicitly listed under - ``deps`` (or in requirements / constraints files referenced in ``deps``) will be used as the constraints. If + versions in order to create ``{env_dir}{/}constraints.txt``. Otherwise the package specifications explicitly listed + under ``deps`` (or in requirements / constraints files referenced in ``deps``) will be used as the constraints. If ``constrain_package_deps`` is false, then this setting has no effect. User configuration ------------------ -tox allows creation of user level config-file to modify default values of the CLI commands. -It is located in the OS-specific user config directory under ``tox/config.ini`` path, see ``tox --help`` output for exact location. -It can be changed via ``TOX_USER_CONFIG_FILE`` environment variable. -Example configuration: +tox allows creation of user level config-file to modify default values of the CLI commands. It is located in the +OS-specific user config directory under ``tox/config.ini`` path, see ``tox --help`` output for exact location. It can be +changed via ``TOX_USER_CONFIG_FILE`` environment variable. Example configuration: .. code-block:: ini @@ -820,7 +820,7 @@ through the ``{...}`` string-substitution pattern. The string inside the curly braces may reference a global or per-environment config key as described above. -In substitutions, the backslash character ``\`` will act as an escape when preceeding +In substitutions, the backslash character ``\`` will act as an escape when preceding ``{``, ``}``, ``:``, ``[``, or ``]``, otherwise the backslash will be reproduced literally:: diff --git a/docs/development.rst b/docs/development.rst index 3c0fb580d..9d16acf6b 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -5,10 +5,10 @@ Getting started --------------- -``tox`` is a volunteer maintained open source project and we welcome contributions of all forms. The sections -below will help you get started with development, testing, and documentation. We’re pleased that you are interested in -working on tox. This document is meant to get you setup to work on tox and to act as a guide and reference -to the development setup. If you face any issues during this process, please +``tox`` is a volunteer maintained open source project and we welcome contributions of all forms. The sections below will +help you get started with development, testing, and documentation. We’re pleased that you are interested in working on +tox. This document is meant to get you setup to work on tox and to act as a guide and reference to the development +setup. If you face any issues during this process, please :issue:`new?title=Trouble+with+development+environment` about it on the issue tracker. Setup @@ -44,8 +44,8 @@ The easiest way to do this is to generate the development tox environment, and t Running tests ~~~~~~~~~~~~~ -tox's tests are written using the :pypi:`pytest` test framework. :pypi:`tox` is used to automate the setup -and execution of tox's tests. +tox's tests are written using the :pypi:`pytest` test framework. :pypi:`tox` is used to automate the setup and execution +of tox's tests. To run tests locally execute: @@ -56,10 +56,9 @@ To run tests locally execute: 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. -``tox`` has been configured to forward any additional arguments it is given to ``pytest``. -This enables the use of pytest's -`rich CLI `_. As an example, you can -select tests using the various ways that pytest provides: +``tox`` has been configured to forward any additional arguments it is given to ``pytest``. This enables the use of +pytest's `rich CLI `_. As an example, +you can select tests using the various ways that pytest provides: .. code-block:: shell @@ -69,8 +68,8 @@ 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). 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. +``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 ~~~~~~~~~~~~~~~ @@ -128,11 +127,10 @@ Contributing Submitting pull requests ~~~~~~~~~~~~~~~~~~~~~~~~ -Submit pull requests (PRs) against the ``main`` 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 ` multiple Python versions and operating systems. Any pull request must -consider and work on all these platforms. +Submit pull requests (PRs) against the ``main`` 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 ` +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 `_ that review quality falls off as patch size @@ -158,10 +156,10 @@ pull request. If needed, project maintainers can manually trigger a restart of a Changelog entries ~~~~~~~~~~~~~~~~~ -The ``changelog.rst`` file is managed using :pypi:`towncrier` and all 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). +The ``changelog.rst`` file is managed using :pypi:`towncrier` and all 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). There is no need to create an issue for trivial changes, e.g. for typo fixes. @@ -184,30 +182,30 @@ Contents of a changelog 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 changelog. +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 changelog. 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 changelog entry is meant for end users and should only contain details relevant to an -end user. +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 changelog entry is meant for end users and should only contain details relevant to an end +user. Becoming a maintainer ~~~~~~~~~~~~~~~~~~~~~ If you want to become an official maintainer, start by helping out. As a first step, we welcome you to triage issues on -tox's issue tracker. tox maintainers provide triage abilities to contributors once they have been around -for some time and contributed positively to the project. This is optional and highly recommended for becoming a -tox maintainer. Later, when you think you're ready, get in touch with one of the maintainers and they will -initiate a vote among the existing maintainers. +tox's issue tracker. tox maintainers provide triage abilities to contributors once they have been around for some time +and contributed positively to the project. This is optional and highly recommended for becoming a tox maintainer. Later, +when you think you're ready, get in touch with one of the maintainers and they will initiate a vote among the existing +maintainers. .. note:: - Upon becoming a maintainer, a person should be given access to various tox-related tooling across - multiple platforms. These are noted here for future reference by the maintainers: + Upon becoming a maintainer, a person should be given access to various tox-related tooling across multiple + platforms. These are noted here for future reference by the maintainers: - GitHub Push Access (provides also CI administration capabilities) - PyPI Publishing Access diff --git a/docs/faq.rst b/docs/faq.rst index 257c6a57d..ec5dd7030 100644 --- a/docs/faq.rst +++ b/docs/faq.rst @@ -78,8 +78,8 @@ directly. pip accepts environment variables as configuration flags, therefore th set_env = PIP_INDEX_URL = https://tox.wiki/pypi/simple -It's considered a best practice to allow the user to change the index server rather than hard code it, allowing them -to use for example a local cache when they are offline. Therefore, a better form of this would be: +It's considered a best practice to allow the user to change the index server rather than hard code it, allowing them to +use for example a local cache when they are offline. Therefore, a better form of this would be: .. code-block:: ini @@ -132,8 +132,8 @@ error to be raised when the package dependencies conflict with the test environm For stronger guarantees, set ``use_frozen_constraints = true`` in the test environment to generate the constraints file based on the exact versions enumerated by the ``list_dependencies_command`` (``pip freeze``). When using frozen constraints, if the package deps are incompatible with any previously installed dependency, an error will be raised. -To use constraints with url, path, or "extras" (``.[tests]``) deps, then you must ``use_frozen_constraints``, as -these types of deps are not valid constraints as specified (see pypa/pip#8210). +To use constraints with url, path, or "extras" (``.[tests]``) deps, then you must ``use_frozen_constraints``, as these +types of deps are not valid constraints as specified (see pypa/pip#8210). Note constraint files are a subset of requirement files. Therefore, it's valid to pass a constraint file wherever you can specify a requirement file. @@ -197,8 +197,8 @@ Customizing virtual environment creation ---------------------------------------- By default tox uses the :pypi:`virtualenv` to create Python virtual environments to run your tools in. To change how tox -creates virtual environments you can set environment variables to customize virtualenv. For example, to provision a given -pip version in the virtual environment you can set ``VIRTUALENV_PIP`` or to enable system site packages use the +creates virtual environments you can set environment variables to customize virtualenv. For example, to provision a +given pip version in the virtual environment you can set ``VIRTUALENV_PIP`` or to enable system site packages use the ``VIRTUALENV_SYSTEM_SITE_PACKAGES``: @@ -210,8 +210,8 @@ pip version in the virtual environment you can set ``VIRTUALENV_PIP`` or to enab VIRTUALENV_PIP==22.1 VIRTUALENV_SYSTEM_SITE_PACKAGES=true -Consult the :pypi:`virtualenv` project for supported values (any CLI flag for virtualenv, in all upper case, prefixed -by the ``VIRTUALENV_`` key). +Consult the :pypi:`virtualenv` project for supported values (any CLI flag for virtualenv, in all upper case, prefixed by +the ``VIRTUALENV_`` key). Building documentation with Sphinx ---------------------------------- @@ -224,8 +224,8 @@ We don't recommend using the Make and Batch file generated by Sphinx, as this ma platform specific. A better solution is to use tox to setup a documentation build environment and invoke sphinx inside it. This solution is cross platform. -For example if the sphinx file structure is under the ``docs`` folder the following configuration will generate -the documentation under ``.tox/docs_out/index.html`` and print out a link to the generated documentation: +For example if the sphinx file structure is under the ``docs`` folder the following configuration will generate the +documentation under ``.tox/docs_out/index.html`` and print out a link to the generated documentation: .. code-block:: ini @@ -270,8 +270,7 @@ substitution logic to avoid duplication: Understanding ``InvocationError`` exit codes -------------------------------------------- -When a command executed by tox fails, it always has a non-zero exit code and an ``InvocationError`` exception is -raised: +When a command executed by tox fails, it always has a non-zero exit code and an ``InvocationError`` exception is raised: .. code-block:: shell @@ -292,9 +291,9 @@ module, an additional hint is given: The signal numbers (e.g. 11 for a segmentation fault) can be found in the "Standard signals" section of the -`signal man page `_. -Their meaning is described in `POSIX signals `_. Beware -that programs may issue custom exit codes with any value, so their documentation should be consulted. +`signal man page `_. Their meaning is described in +`POSIX signals `_. Beware that programs may issue custom exit +codes with any value, so their documentation should be consulted. Sometimes, no exit code is given at all. An example may be found in @@ -304,8 +303,8 @@ Sometimes, no exit code is given at all. An example may be found in Access full logs ---------------- -If you want to access the full logs you need to write ``-q`` and ``-v`` as -individual tox arguments and avoid combining them into a single one. +If you want to access the full logs you need to write ``-q`` and ``-v`` as individual tox arguments and avoid combining +them into a single one. Running within a Docker container --------------------------------- @@ -354,12 +353,11 @@ Testing end-of-life Python versions ----------------------------------- ``tox`` uses ``virtualenv`` under its hood for managing virtual environments. +`Virtualenv 20.22.0 `_ dropped support for all +Python versions smaller or equal to Python 3.6. -`Virtualenv 20.22.0 `_ -dropped support for all Python versions smaller or equal to Python 3.6. - -If you need to test against e.g. Python 2.7, 3.5 or 3.6, you need to add the -following ``requires`` statement to your ``tox.ini`` configuration files. +If you need to test against e.g. Python 2.7, 3.5 or 3.6, you need to add the following ``requires`` statement to your +``tox.ini`` configuration files. .. code-block:: ini diff --git a/docs/installation.rst b/docs/installation.rst index 01c248abb..ac2f21946 100644 --- a/docs/installation.rst +++ b/docs/installation.rst @@ -40,7 +40,7 @@ sdist ~~~~~ When installing via a source distribution you need an installer that handles the :pep:`517` specification. In case of ``pip`` this is version ``18.0.0`` or later (released in July 2018). If you cannot upgrade your pip to support this you -need to ensure that the build requirements from :gh:`pyproject.toml ` are +need to ensure that the build requirements from :gh:`pyproject.toml ` are satisfied before triggering the installation. via ``setup.py``