Merge branch '3.0-doc-wording' into 'proposed/3.0'

Grammar and clarity improvements.

Improve grammar and clarity throughout the documentation. 

See merge request !62

docs/source/dev/formatters.rst

@@ -4,7 +4,7 @@
  Developing a Formatting Plugin for Flake8
 ===========================================
 
-Flake8 added the ability to develop custom formatting plugins in version
+Flake8 allowed for custom formatting plugins in version
 3.0.0. Let's write a plugin together:
 
 .. code-block:: python

docs/source/dev/index.rst

@@ -4,9 +4,9 @@
 
 Since Flake8 2.0, the Flake8 tool has allowed for extensions and custom
 plugins. In Flake8 3.0, we're expanding that ability to customize and
-extend **and** we're attempting to thoroughly document it too. Some of the
+extend **and** we're attempting to thoroughly document it. Some of the
 documentation in this section will reference third-party documentation
-in order to reduce duplication and to point you, the developer, towards
+to reduce duplication and to point you, the developer, towards
 the authoritative documentation for those pieces.
 
 .. toctree::

docs/source/dev/registering_plugins.rst

@@ -4,9 +4,9 @@
  Registering a Plugin with Flake8
 ==================================
 
-To register any kind of plugin with Flake8, you need a few things:
+To register any kind of plugin with Flake8, you need:
 
-#. You need a way to install the plugin (whether it is packaged on its own or
+#. A way to install the plugin (whether it is packaged on its own or
    as part of something else). In this section, we will use a ``setup.py``
    written for an example plugin.
 
@@ -15,7 +15,7 @@ To register any kind of plugin with Flake8, you need a few things:
 #. A somewhat recent version of setuptools (newer than 0.7.0 but preferably as
    recent as you can attain).
 
-Flake8 presently relies on a functionality provided by setuptools called
+Flake8 relies on functionality provided by setuptools called
 `Entry Points`_. These allow any package to register a plugin with Flake8 via
 that package's ``setup.py`` file.
 

docs/source/index.rst

@@ -30,7 +30,7 @@ can instead use:
     It is **very** important to install Flake8 on the *correct* version of
     Python for your needs. If you want Flake8 to properly parse new language
     features in Python 3.5 (for example), you need it to be installed on 3.5
-    for those features to be understandable. In many ways, Flake8 is tied to
+    for flake8 to understand those features. In many ways, Flake8 is tied to
     the version of Python on which it runs.
 
 Quickstart

docs/source/internal/checker.rst

@@ -2,17 +2,17 @@
  How Checks are Run
 ====================
 
-In Flake8 2.x, Flake8 delegated check running to pep8. In 3.0 we have taken
-that responsibility upon ourselves. This has allowed us to simplify our
-handling of the ``--jobs`` parameter (using :mod:`multiprocessing`) as well as
-simplifying our fallback in the event something goes awry with concurency.
+In Flake8 2.x, Flake8 delegated check running to pep8. In 3.0 flake8 takes
+on that responsibility. This has allowed for simpler
+handling of the ``--jobs`` parameter (using :mod:`multiprocessing`) and
+simplified our fallback if something goes awry with concurency.
 At the lowest level we have a |FileChecker|. Instances of |FileChecker| are
 created for *each* file to be analyzed by Flake8. Each instance, has a copy of
 all of the plugins registered with setuptools in the ``flake8.extension``
 entry-point group.
 
 The |FileChecker| instances are managed by an instance of |Manager|. The
-|Manager| instance is what handles creating sub-processes with
+|Manager| instance handles creating sub-processes with
 :mod:`multiprocessing` module and falling back to running checks in serial if
 an operating system level error arises. When creating |FileChecker| instances,
 the |Manager| is responsible for determining if a particular file has been
@@ -23,10 +23,10 @@ Processing Files
 ----------------
 
 Unfortunately, since Flake8 took over check running from pep8/pycodestyle, it
-also was required to take over parsing and processing files for the checkers
-to use. Since we couldn't reuse pycodestyle's functionality (since it did not
-separate cleanly the processing from check running) we isolated that function
-into the :class:`~flake8.processor.FileProcessor` class. Further, we moved
+also had to take over parsing and processing files for the checkers
+to use. Since it couldn't reuse pycodestyle's functionality (since it did not
+separate cleanly the processing from check running) that function was isolated
+into the :class:`~flake8.processor.FileProcessor` class. We moved
 several helper functions into the :mod:`flake8.processor` module (see also
 :ref:`Processor Utility Functions <processor_utility_functions>`).
 

docs/source/internal/cli.rst

@@ -7,8 +7,8 @@ command line, :func:`~flake8.main.cli.main` is run which handles
 management of the application.
 
 User input is parsed *twice* to accomodate logging and verbosity options
-passed by the user as early as possible so as much logging can be produced as
-possible.
+passed by the user as early as possible.
+This is so as much logging can be produced as possible.
 
 The default flake8 options are registered by
 :func:`~flake8.main.options.register_default_options`. Trying to register

docs/source/internal/contributing.rst

@@ -2,7 +2,7 @@
  Contributing to Flake8
 ========================
 
-We encourage multiple methods of participation in Flake8:
+There are many ways to contriubte to Flake8, and we encourage them all:
 
 - contributing bug reports and feature requests
 
@@ -44,7 +44,7 @@ To contribute to Flake8's development, you simply need:
 
         python<version> -m pip install --user tox
 
-- and your favorite editor
+- your favorite editor
 
 
 Filing a Bug
@@ -166,7 +166,7 @@ Reviewing and Triaging Issues and Merge Requests
 ================================================
 
 When reviewing other people's merge requests and issues, please be
-**especially** mindful of how the words you choose can be ready by someone
+**especially** mindful of how the words you choose can be read by someone
 else. We strive for professional code reviews that do not insult the
 contributor's intelligence or impugn their character. The code review
 should be focused on the code, it's effectiveness, and whether it is
@@ -175,8 +175,8 @@ appropriate for Flake8.
 If you have the ability to edit an issue or merge request's labels, please do
 so to make search and prioritization easier.
 
-Flake8 uses milestones with both issues and merge requests to provide
-other contributors direction about when an issue or merge request will be
+Flake8 uses milestones with both issues and merge requests. This provides
+direction for other contributors about when an issue or merge request will be
 delivered.
 
 

docs/source/internal/formatters.rst

@@ -20,7 +20,7 @@ Default Formatter
 The |DefaultFormatter| continues to use the same default format string as
 pep8: ``'%(path)s:%(row)d:%(col)d: %(code)s %(text)s'``.
 
-In order to provide the default functionality it overrides two methods:
+To provide the default functionality it overrides two methods:
 
 #. ``after_init``
 

docs/source/internal/option_handling.rst

@@ -6,8 +6,8 @@ Option Management
 
 Command-line options are often also set in configuration files for Flake8.
 While not all options are meant to be parsed from configuration files, many
-default options are also parsed from configuration files as are most plugin
-options.
+default options are also parsed from configuration files as well as
+most plugin options.
 
 In Flake8 2, plugins received a :class:`optparse.OptionParser` instance and
 called :meth:`optparse.OptionParser.add_option` to register options. If the
@@ -19,7 +19,7 @@ also had to do something like:
     parser.config_options.append('my_config_option')
     parser.config_options.extend(['config_opt1', 'config_opt2'])
 
-This was previously undocumented and led to a lot of confusion as to why
+This was previously undocumented and led to a lot of confusion about why
 registered options were not automatically parsed from configuration files.
 
 Since Flake8 3 was rewritten from scratch, we decided to take a different
@@ -40,8 +40,8 @@ three new parameters:
 - ``normalize_paths``
 
 The last two are not specifically for configuration file handling, but they
-do improve that dramatically. We found that there were options that when
-specified in a configuration file, lended themselves to being split across
+do improve that dramatically. We found that there were options that, when
+specified in a configuration file, often necessitated being spit
 multiple lines and those options were almost always comma-separated. For
 example, let's consider a user's list of ignored error codes for a project:
 
@@ -82,7 +82,7 @@ Presently OpenStack's Nova project has this line in their `tox.ini`_:
 
     exclude = .venv,.git,.tox,dist,doc,*openstack/common/*,*lib/python*,*egg,build,tools/xenserver*,releasenotes
 
-I think we can all agree that this would be easier to read like this:
+We think we can all agree that this would be easier to read like this:
 
 .. code-block:: ini
 
@@ -104,7 +104,7 @@ both ``comma_separated_list=True`` and ``normalize_paths=True`` because we
 want the paths to be provided to us with some consistency (either all absolute
 paths or not).
 
-Now let's look at how this would actually be utilized. Most plugin developers
+Now let's look at how this will actually be used. Most plugin developers
 will receive an instance of :class:`~flake8.options.manager.OptionManager` so
 to ease the transition we kept the same API as the
 :class:`optparse.OptionParser` object. The only difference is that

docs/source/internal/plugin_handling.rst

@@ -13,8 +13,8 @@ checks. It now supports:
 
 - listeners to auto-correct violations of checks
 
-To facilitate this, Flake8 needed a more mature way of managing plugins. As
-such, we developed the |PluginManager| which accepts a namespace and will load
+To facilitate this, Flake8 needed a more mature way of managing plugins.
+Thus, we developed the |PluginManager| which accepts a namespace and will load
 the plugins for that namespace. A |PluginManager| creates and manages many
 |Plugin| instances.
 
@@ -24,7 +24,7 @@ The entry-point will be loaded either by calling
 attribute. We also use this abstraction to retrieve options that the plugin
 wishes to register and parse.
 
-The only public method that the |PluginManager| provides is
+The only public method the |PluginManager| provides is
 :meth:`~flake8.plugins.manager.PluginManager.map`. This will accept a function
 (or other callable) and call it with each plugin as the first parameter.
 
@@ -59,7 +59,7 @@ Notifying Listener Plugins
 One of the interesting challenges with allowing plugins to be notified each
 time an error or warning is emitted by a checker is finding listeners quickly
 and efficiently. It makes sense to allow a listener to listen for a certain
-class of warnings or just a specific warning. As such, we need to allow all
+class of warnings or just a specific warning. Hence, we need to allow all
 plugins that listen to a specific warning or class to be notified. For
 example, someone might register a listener for ``E1`` and another for ``E111``
 if ``E111`` is triggered by the code, both listeners should be notified.

docs/source/internal/utils.rst

@@ -120,7 +120,7 @@ argument so we can check the parameters of the plugin consistently.
 
 .. autofunction:: flake8.utils.parse_unified_diff
 
-In order to handle usage of :option:`flake8 --diff`, Flake8 needs to be able
+To handle usage of :option:`flake8 --diff`, Flake8 needs to be able
 to parse the name of the files in the diff as well as the ranges indicated the
 sections that have been changed. This function either accepts the diff as an
 argument or reads the diff from standard-in. It then returns a dictionary with

docs/source/user/configuration.rst

@@ -24,7 +24,7 @@ Remember that you want to specify certain options without writing
 Configuration Locations
 =======================
 
-Presently, Flake8 supports storing its configuration in the following places:
+Flake8 supports storing its configuration in the following places:
 
 - Your top-level user directory
 
@@ -163,7 +163,7 @@ This would allow us to add comments for why we're excluding items, e.g.,
     :mod:`configparser` backport from PyPI. That backport enables us to
     support this behaviour on all supported versions of Python.
 
-    Please do **not** open issues about this dependency.
+    Please do **not** open issues about this dependency to Flake8.
 
 .. note::
 

docs/source/user/ignoring-errors.rst

@@ -4,7 +4,7 @@
 
 By default, |Flake8| has a list of error codes that it ignores. The list used
 by a version of |Flake8| may be different than the list used by a different
-version. To determine the default list, using :option:`flake8 --help` will
+version. To see the default list, :option:`flake8 --help` will
 show the output with the current default list.
 
 
@@ -42,7 +42,7 @@ specific error code on a specific line. Let's take for example a line like
     example = lambda: 'example'
 
 Sometimes we genuinely need something this simple. We could instead define
-a function like we normally would but in some contexts that distracts from
+a function like we normally would. Note, in some contexts this distracts from
 what is actually happening. In those cases, we can also do:
 
 .. code-block:: python

docs/source/user/index.rst

@@ -2,13 +2,13 @@
  Using Flake8
 ==============
 
-Flake8 can be used in many ways:
+Flake8 can be used in many ways. A few:
 
-- invoking it on the command-line
+- invoked on the command-line
 
-- invoking it via Python
+- invoked via Python
 
-- having it called by Git or Mercurial on or around committing
+- called by Git or Mercurial on or around committing
 
 This guide will cover all of these and the nuances for using Flake8.
 

docs/source/user/options.rst

@@ -228,7 +228,7 @@
     - pylint
 
     Other formatters can be installed. Refer to their documentation for the
-    name to use to select them. Further, users can specify they're own format
+    name to use to select them. Further, users can specify their own format
     string. The variables available are:
 
     - code