Minor updates to the documentation (#1540)

Signed-off-by: Bernat Gabor <[email protected]>

azure-pipelines.yml

@@ -115,4 +115,4 @@ jobs:
     parameters:
       external_feed: 'gb'
       pypi_remote: 'pypi-gb'
-      dependsOn: [fix_lint, embed, docs, report_coverage, dev, readme]
+      dependsOn: [fix_lint, docs, report_coverage, dev, readme, zipapp, upgrade]

docs/changes.rst

@@ -5,11 +5,14 @@ Release History
 
 .. towncrier release notes start
 
-v20.0.0 (2020-02-10)
---------------------
-
-No significant changes.
-
+v20.0.0. (2020-02-10)
+---------------------
+
+Improved Documentation - 20.0.0.
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+- Fixes typos, repeated words and inconsistent heading spacing. Rephrase parts of the development documentation and CLI
+  documentation. Expands shorthands like ``env var`` and ``config`` to their full forms. Uses descriptions from respective
+  documentation, for projects listed in ``related links`` - by :user:`pradyunsg`. (`#1540 <https://github.com/pypa/virtualenv/issues/1540>`_)
 
 v20.0.0b2 (2020-02-04)
 ----------------------

docs/cli_interface.rst

@@ -3,18 +3,20 @@ CLI interface
 
 .. _cli_flags:
 
-cli flags
+CLI flags
 ~~~~~~~~~
 
-``virtualenv`` is primarily a command line interface application. It's mainly aimed to be used from a command line, as
-such you'll need to to have a shell to run it. Then you can type in ``virtualenv`` (name of the application) followed by
-flags that control its behaviour. All options do have a sensible default, so if you pass no options you'll get a
-virtual environment in the current working directories ``venv`` folder. The Default values for the command line
-options can be modified either via the :ref:`conf_file` or :ref:`env_vars`. Environment variables takes priority over
-the configuration file values (the ``--help`` will show if a default comes from the environment variable as the help
-message will end in this case either with ``via env var`` or ``via config file``).
+``virtualenv`` is primarily a command line application.
 
-Below you can see the options you can pass in, together with its default value, and a short description of what it does:
+It modifies the environment variables in a shell to create an isolated Python environment, so you'll need to have a
+shell to run it. You can type in ``virtualenv`` (name of the application) followed by flags that control its
+behaviour. All options have sensible defaults, so you'll get a working virtual environment in a ``venv`` folder even
+if you don't pass any options. The default values for the command line options can be overridden via the
+:ref:`conf_file` or :ref:`env_vars`. Environment variables takes priority over the configuration file values
+(``--help`` will show if a default comes from the environment variable as the help message will end in this case
+with environment variables or the configuration file).
+
+The options that can be passed to virtualenv, along with their default values and a short description are listed below.
 
 :command:`virtualenv [OPTIONS]`
 
@@ -30,19 +32,19 @@ Defaults
 Configuration file
 ^^^^^^^^^^^^^^^^^^
 
-virtualenv looks for a standard ini config file. The exact place depends on the operating system you're using, as
-determined by :pypi:`appdirs` application data definition. The config file location is printed as epilog for the CLI
-tools help message.
+virtualenv looks for a standard ini configuration file. The exact location depends on the operating system you're using,
+as determined by :pypi:`appdirs` application data definition. The configuration file location is printed as at the end of
+the output when ``--help`` is passed.
 
-The keys of the settings are derived from the long command line option, e.g. the option :option:`--python <python>`
-would look like this:
+The keys of the settings are derived from the long command line option. For example, :option:`--python <python>`
+would be specified as:
 
 .. code-block:: ini
 
   [virtualenv]
   python = /opt/python-3.3/bin/python
 
-Appending options like :option:`extra-search-dir` can be written on multiple lines:
+Options that take multiple values, like :option:`extra-search-dir` can be specified as:
 
 .. code-block:: ini
 
@@ -56,25 +58,25 @@ Appending options like :option:`extra-search-dir` can be written on multiple lin
 Environment Variables
 ^^^^^^^^^^^^^^^^^^^^^
 
-Each command line option is automatically used to look for environment variables with the name format
-``VIRTUALENV_<UPPER_NAME>``. That means the name of the command line options are capitalized and have dashes (``'-'``)
-replaced with underscores (``'_'``).
+Each command line option has a corresponding environment variables with the name format
+``VIRTUALENV_<UPPER_NAME>``. The ``UPPER_NAME`` is the name of the command line options capitalized and
+dashes (``'-'``) replaced with underscores (``'_'``).
 
-For example, to automatically use a custom Python binary instead of the one virtualenv is run with you can also set an
-environment variable:
+For example, to use a custom Python binary, instead of the one virtualenv is run with, you can set the environment
+variable ``VIRTUALENV_PYTHON`` like:
 
 .. code-block:: console
 
    env VIRTUALENV_PYTHON=/opt/python-3.8/bin/python virtualenv
 
-This also works for appending command line options, like :option:`extra-search-dir`. Just pass a literal newline
-between the passed values, e.g.:
+This also works for appending command line options, like :option:`extra-search-dir`, where a literal newline
+is used to separate the values:
 
 .. code-block:: console
 
   env VIRTUALENV_EXTRA_SEARCH_DIR="/path/to/dists\n/path/to/other/dists" virtualenv
 
-is the same as calling:
+The equivalent CLI-flags based invocation, for the above example, would be:
 
 .. code-block:: console
 

docs/development.rst

@@ -4,6 +4,7 @@ Development
 Getting started
 ---------------
 
+
 ``virtualenv`` 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 virtualenv. This document is meant to get you setup to work on virtualenv and to act as a guide and reference
@@ -13,19 +14,22 @@ the issue tracker.
 
 Setup
 ~~~~~
-virtualenv is a command line application written in Python, as such you'll need:
 
-- **the source code**  is available on `GitHub <https://github.com/pypa/pip>`_, so use some client to clone the
-  repository via:
+virtualenv is a command line application written in Python. To work on it, you'll need:
+
+- **Source code**: available on `GitHub <https://github.com/pypa/virtualenv>`_. You can use ``git`` to clone the
+    repository:
 
   .. code-block:: console
 
       git clone https://github.com/pypa/virtualenv
       cd virtualenv
-- a **Python interpreter** is needed, we recommend using ``CPython``, you can use
-  `this guide <https://realpython.com/installing-python/>`_ to do that
-- to automatically get the projects development dependencies and run the test suite you can use the :pypi:`tox` tool,
-  we recommend using the `pipx <https://pipxproject.github.io/pipx/>`_ project to achieve this.
+
+- **Python interpreter**: We recommend using ``CPython``. You can use
+  `this guide <https://realpython.com/installing-python/>`_ to set it up.
+
+- :pypi:`tox`: to automatically get the projects development dependencies and run the test suite. We recommend
+  installing it using `pipx <https://pipxproject.github.io/pipx/>`_.
 
 Running from source tree
 ~~~~~~~~~~~~~~~~~~~~~~~~
@@ -51,8 +55,8 @@ To run tests locally execute:
 
     tox -e py
 
-This will run the test suite for the same Python version as under what ``tox`` is installed. Alternatively you can
-specify a specific version of python by using the ``pyxy`` format, such as: ``py38``, ``pypy3``, etc.
+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
@@ -68,7 +72,7 @@ select tests using the various ways that pytest provides:
 
 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
-all tests are run; so if all tests succeed locally it may still fail in the CI.
+all tests are run; so even if all tests succeed locally for you, they may still fail in the CI.
 
 Running linters
 ~~~~~~~~~~~~~~~
@@ -101,7 +105,8 @@ that folder.
 
 Release
 ~~~~~~~
-Virtualenv's release schedule is tied to ``pip``, ``setuptools`` and ``wheel``. We bundle the latest version of these
+
+virtualenv's release schedule is tied to ``pip``, ``setuptools`` and ``wheel``. We bundle the latest version of these
 libraries so each time there's a new version of any of these, there will be a new virtualenv release shortly afterwards
 (we usually wait just a few days to avoid pulling in any broken releases).
 
@@ -117,12 +122,11 @@ License. Provide tests that cover your changes and run the tests locally first.
 :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 easier 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 be broken up into smaller, independent parts which can be reviewed and merged
-individually.
+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
+be broken up into smaller, independent parts which can be reviewed and merged individually.
 
 Additionally, avoid including "cosmetic" changes to code that is unrelated to your change, as these make reviewing the
 PR more difficult. Examples include re-flowing text in comments or documentation, or addition or removal of blank lines
@@ -144,7 +148,7 @@ NEWS entries
 ~~~~~~~~~~~~
 
 The ``changes.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
+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).
 
@@ -161,7 +165,7 @@ Thus if your issue or PR number is ``1234`` and this change is fixing a bug, the
 ``docs/changelog/1234.bugfix.rst``. PRs can span multiple categories by creating multiple files (for instance, if you
 added a feature and deprecated/removed the old feature at the same time, you would create
 ``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 exact same contents and :pypi:`towncrier` will deduplicate them.
+you may create a file for each of them with the same contents and :pypi:`towncrier` will deduplicate them.
 
 Contents of a NEWS entry
 ^^^^^^^^^^^^^^^^^^^^^^^^
@@ -172,7 +176,7 @@ the affected issues when rendering the news file.
 
 In order to maintain a consistent style in the ``changes.rst`` file, it is preferred to keep the news entry 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
+``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.
@@ -185,7 +189,6 @@ don't change anything as far as the public is concerned, typo fixes, white space
 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

@@ -32,17 +32,17 @@ integrated into the standard library under the `venv module <https://docs.python
 ``venv`` module does not offer all features of this library, to name just a few more prominent:
 
 - is slower (by not having the ``app-data`` seed method),
-- is not as extensible,
+- is not as extendable,
 - cannot create virtual environments for arbitrarily installed python versions (and automatically discover these),
 - is not upgrade-able via `pip <https://pip.pypa.io/en/stable/installing/>`_,
 - does not have as rich programmatic API (describe virtual environments without creating them).
 
 The basic problem being addressed is one of dependencies and versions, and indirectly permissions.
 Imagine you have an application that needs version ``1`` of ``LibFoo``, but another application requires version
-``2``. How can you use both these libraries?  If you install everything into your host python (e.g. ``python3.8``)
+``2``. How can you use both these libraries? If you install everything into your host python (e.g. ``python3.8``)
 it's easy to end up in a situation where two packages have conflicting requirements.
 
-Or more generally, what if you want to install an application *and leave it be*?  If an application works, any change
+Or more generally, what if you want to install an application *and leave it be*? If an application works, any change
 in its libraries or the versions of those libraries can break the application. Also, what if you can't install packages
 into the global ``site-packages`` directory, due to not having permissions to change the host python environment?
 
@@ -53,14 +53,14 @@ libraries either).
 Useful links
 ------------
 
-**Related projects, abstsractions on top of it**
+**Related projects, that build abstractions on top of virtualenv**
 
-* :pypi:`virtualenvwrapper` is a useful set of scripts to make your workflow with many virtualenv even easier
-* :pypi:`pew` is another wrapper for virtualenv that makes use of a different activation technique
-* :pypi:`tox` - integrates setting up and running tests within virtual environments driven by a ``tox.ini``
+* :pypi:`virtualenvwrapper` - a useful set of scripts for creating and deleting virtual environments
+* :pypi:`pew` - provides a set of commands to manage multiple virtual environments
+* :pypi:`tox` - a generic virtualenv management and test automation command line tool, driven by a ``tox.ini``
   configuration file
-* :pypi:`nox` - integrates setting up and running tests within virtual environments driven by a ``nox.py``
-  python file
+* :pypi:`nox` - a tool that automates testing in multiple Python environments, similar to tox,
+  driven by a ``noxfile.py`` configuration file
 
 **Tutorials**
 

docs/installation.rst

@@ -15,6 +15,7 @@ benefit that later you'll be able to upgrade virtualenv without affecting other
 
 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
 another package manager. ``pip`` might not coordinate with those tools, and may leave your system in an

docs/user_guide.rst

@@ -10,7 +10,7 @@ Virtualenv has one basic command:
 
     virtualenv
 
-this will create a python virtual environment of the same version as virtualenv is installed into under path
+This will create a python virtual environment of the same version as virtualenv is installed into under path
 ``venv``. The path where to generate the virtual environment can be changed via a positional argument being passed in,
 see the :option:`dest` flag. The command line tool has quite a few of flags that modify the components behaviour, for a
 full list make sure to check out :ref:`cli_flags`.
@@ -42,10 +42,10 @@ python ``3.8``, virtualenv will by default create virtual environments that are
 
 Created python virtual environments are usually not self-contained. A complete python packaging is usually made up of
 thousand of files, so it's not efficient to install the entire python again into a new folder. Instead virtual
-environments are mere shells, that contain very little within itself, and borrow most from the system python (this is
-what you installed, when you installed python itself). This does mean that if you upgrade your system python your
-virtual environments *might* break, so watch out. The upside of this referring to the system python is that creating
-virtual environments can be very fast.
+environments are mere shells, that contain little within itself, and borrow most from the system python (this is what
+you installed, when you installed python itself). This does mean that if you upgrade your system python your virtual
+environments *might* break, so watch out. The upside of this referring to the system python is that creating virtual
+environments can be fast.
 
 Here we'll describe the builtin mechanism (note this can be extended though by plugins). The CLI flag :option:`p` or
 :option:`python` allows you to specify a python specifier for what type of virtual environment you would like, the

setup.cfg

@@ -86,6 +86,7 @@ docs =
     sphinx-argparse >= 0.2.5, <1
     sphinx-rtd-theme >= 0.4.3, <1
     towncrier >= 19.9.0rc1
+    proselint >= 0.10.2, <1
 testing =
     packaging>=20.0;python_version>"3.4"
     pytest >= 4.0.0, <6

tox.ini

@@ -75,6 +75,7 @@ basepython = python3.8
 description = build documentation
 extras = docs
 commands =
+    python -c 'import glob; import subprocess; subprocess.call(["proselint"] + glob.glob("docs/*.rst") + glob.glob("docs/**/*.rst"))'
     sphinx-build -d "{envtmpdir}/doctree" docs "{toxworkdir}/docs_out" --color -b html {posargs}
     python -c 'import pathlib; print("documentation available under file://\{0\}".format(pathlib.Path(r"{toxworkdir}") / "docs_out" / "index.html"))'