Use |Flake8| consistently throughout documentation

docs/source/dev/formatters.rst

@@ -4,7 +4,7 @@
  Developing a Formatting Plugin for Flake8
 ===========================================
 
-Flake8 allowed for 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
@@ -17,11 +17,12 @@ Flake8 allowed for custom formatting plugins in version
 
         pass
 
-We notice, as soon as we start, that we inherit from Flake8's
+We notice, as soon as we start, that we inherit from |Flake8|'s
 :class:`~flake8.formatting.base.BaseFormatter` class. If we follow the
 :ref:`instructions to register a plugin <register-a-plugin>` and try to use
-our example formatter, e.g., ``flake8 --format=example`` then Flake8 will fail
+our example formatter, e.g., ``flake8 --format=example`` then
-because we did not implement the ``format`` method. Let's do that next.
+|Flake8| will fail because we did not implement the ``format`` method.
+Let's do that next.
 
 .. code-block:: python
 
@@ -34,7 +35,7 @@ because we did not implement the ``format`` method. Let's do that next.
 With that we're done. Obviously this isn't a very useful formatter, but it
 should highlight the simplicitly of creating a formatter with Flake8. If we
 wanted to instead create a formatter that aggregated the results and returned
-XML, JSON, or subunit we could also do that. Flake8 interacts with the
+XML, JSON, or subunit we could also do that. |Flake8| interacts with the
 formatter in two ways:
 
 #. It creates the formatter and provides it the options parsed from the

docs/source/dev/index.rst

@@ -2,8 +2,8 @@
  Writing Plugins for Flake8
 ============================
 
-Since Flake8 2.0, the Flake8 tool has allowed for extensions and custom
+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
+plugins. In |Flake8| 3.0, we're expanding that ability to customize and
 extend **and** we're attempting to thoroughly document it. Some of the
 documentation in this section will reference third-party documentation
 to reduce duplication and to point you, the developer, towards

docs/source/dev/plugin_parameters.rst

@@ -4,15 +4,15 @@
  Receiving Information For A Check Plugin
 ==========================================
 
-Plugins to Flake8 have a great deal of information that they can request from
+Plugins to |Flake8| have a great deal of information that they can request
-a :class:`~flake8.processor.FileProcessor` instance. Historically, Flake8 has
+from a :class:`~flake8.processor.FileProcessor` instance. Historically,
-supported two types of plugins:
+|Flake8| has supported two types of plugins:
 
 #. classes that accept parsed abstract syntax trees (ASTs)
 
 #. functions that accept a range of arguments
 
-Flake8 now does not distinguish between the two types of plugins. Any plugin
+|Flake8| now does not distinguish between the two types of plugins. Any plugin
 can accept either an AST or a range of arguments. Further, any plugin that has
 certain callable attributes can also register options and receive parsed
 options.
@@ -21,8 +21,8 @@ options.
 Indicating Desired Data
 =======================
 
-Flake8 inspects the plugin's signature to determine what parameters it expects
+|Flake8| inspects the plugin's signature to determine what parameters it
-using :func:`flake8.utils.parameters_for`.
+expects using :func:`flake8.utils.parameters_for`.
 :attr:`flake8.plugins.manager.Plugin.parameters` caches the values so that
 each plugin makes that fairly expensive call once per plugin. When processing
 a file, a plugin can ask for any of the following:
@@ -56,7 +56,7 @@ Any plugin that has callable attributes ``provide_options`` and
 
 Your ``register_options`` function should expect to receive an instance of
 |OptionManager|. An |OptionManager| instance behaves very similarly to
-:class:`optparse.OptionParser`. It, however, uses the layer that Flake8 has
+:class:`optparse.OptionParser`. It, however, uses the layer that |Flake8| has
 developed on top of :mod:`optparse` to also handle configuration file parsing.
 :meth:`~flake8.options.manager.OptionManager.add_option` creates an |Option|
 which accepts the same parameters as :mod:`optparse` as well as three extra
@@ -65,7 +65,7 @@ boolean parameters:
 - ``parse_from_config``
 
   The command-line option should also be parsed from config files discovered
-  by Flake8.
+  by |Flake8|.
 
   .. note::
 
@@ -91,8 +91,8 @@ boolean parameters:
   allow a comma-separated list of paths.
 
 Each of these options works individually or can be combined. Let's look at a
-couple examples from Flake8. In each example, we will have ``option_manager``
+couple examples from |Flake8|. In each example, we will have
-which is an instance of |OptionManager|.
+``option_manager`` which is an instance of |OptionManager|.
 
 .. code-block:: python
 
@@ -143,7 +143,7 @@ documentation of :mod:`optparse`.
 Accessing Parsed Options
 ========================
 
-When a plugin has a callable ``provide_options`` attribute, Flake8 will call
+When a plugin has a callable ``provide_options`` attribute, |Flake8| will call
 it and attempt to provide the |OptionManager| instance, the parsed options
 which will be an instance of :class:`optparse.Values`, and the extra arguments
 that were not parsed by the |OptionManager|. If that fails, we will just pass

docs/source/dev/registering_plugins.rst

@@ -4,7 +4,7 @@
  Registering a Plugin with Flake8
 ==================================
 
-To register any kind of plugin with Flake8, you need:
+To register any kind of plugin with |Flake8|, you need:
 
 #. 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``
@@ -15,9 +15,9 @@ To register any kind of plugin with Flake8, you need:
 #. A somewhat recent version of setuptools (newer than 0.7.0 but preferably as
    recent as you can attain).
 
-Flake8 relies on 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
+`Entry Points`_. These allow any package to register a plugin with |Flake8|
-that package's ``setup.py`` file.
+via that package's ``setup.py`` file.
 
 Let's presume that we already have our plugin written and it's in a module
 called ``flake8_example``. We might have a ``setup.py`` that looks something
@@ -82,7 +82,7 @@ Note specifically these lines:
 We tell setuptools to register our entry point "X" inside the specific
 grouping of entry-points that flake8 should look in.
 
-Flake8 presently looks at three groups:
+|Flake8| presently looks at three groups:
 
 - ``flake8.extension``
 
@@ -90,7 +90,7 @@ Flake8 presently looks at three groups:
 
 - ``flake8.report``
 
-If your plugin is one that adds checks to Flake8, you will use
+If your plugin is one that adds checks to |Flake8|, you will use
 ``flake8.extension``. If your plugin automatically fixes errors in code, you
 will use ``flake8.listen``.  Finally, if your plugin performs extra report
 handling (formatting, filtering, etc.) it will use ``flake8.report``.

docs/source/index.rst

@@ -7,18 +7,21 @@
  Flake8: Your Tool For Style Guide Enforcement
 ===============================================
 
+Quickstart
+==========
+
 .. _installation-guide:
 
 Installation
-============
+------------
 
-To install Flake8, open an interactive shell and run:
+To install |Flake8|, open an interactive shell and run:
 
 .. code::
 
     python<version> -m pip install flake8
 
-If you want Flake8 to be installed for your default Python installation, you
+If you want |Flake8| to be installed for your default Python installation, you
 can instead use:
 
 .. code::
@@ -27,16 +30,16 @@ can instead use:
 
 .. note::
 
-    It is **very** important to install Flake8 on the *correct* version of
+    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
+    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 flake8 to understand those features. 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
+Using Flake8
-==========
+------------
 
-To start using Flake8, open an interactive shell and run:
+To start using |Flake8|, open an interactive shell and run:
 
 .. code::
 
@@ -46,7 +49,7 @@ To start using Flake8, open an interactive shell and run:
 
 .. note::
 
-    If you have installed Flake8 on a particular version of Python (or on
+    If you have installed |Flake8| on a particular version of Python (or on
     several versions), it may be best to instead run ``python<version> -m
     flake8``.
 
@@ -55,20 +58,24 @@ If you only want to see the instances of a specific warning or error, you can
 
 .. code::
 
-    flake8 --select <Error> path/to/code/
+    flake8 --select E123,W503 path/to/code/
 
 Alternatively, if you want to *ignore* only one specific warning or error:
 
 .. code::
 
-    flake8 --ignore <Error> path/to/code/
+    flake8 --ignore E24,W504 path/to/code/
 
 Please read our user guide for more information about how to use and configure
-Flake8.
+|Flake8|.
 
 User Guide
 ==========
 
+All users of |Flake8| should read this portion of the documentation. This
+provides examples and documentation around |Flake8|'s assortment of options
+and how to specify them on the command-line or in configuration files.
+
 .. toctree::
     :maxdepth: 2
 
@@ -77,13 +84,22 @@ User Guide
 Plugin Developer Guide
 ======================
 
+If you're maintaining a plugin for |Flake8| or creating a new one, you should
+read this section of the documentation. It explains how you can write your
+plugins and distribute them to others.
+
 .. toctree::
     :maxdepth: 2
 
     dev/index
 
-Developer Guide
+Contributor Guide
-===============
+=================
+
+If you are reading |Flake8|'s source code for fun or looking to contribute,
+you should read this portion of the documentation. This is a mix of documenting
+the internal-only interfaces |Flake8| and documenting reasoning for Flake8's
+design.
 
 .. toctree::
     :maxdepth: 2
@@ -98,9 +114,8 @@ Release Notes and History
 
     release-notes/index
 
-Indices and tables
+General Indices
-==================
+===============
 
 * :ref:`genindex`
-* :ref:`modindex`
+* :ref:`Index of Documented Public Modules <modindex>`
-* :ref:`search`

docs/source/internal/checker.rst

@@ -2,13 +2,13 @@
  How Checks are Run
 ====================
 
-In Flake8 2.x, Flake8 delegated check running to pep8. In 3.0 flake8 takes
+In |Flake8| 2.x, |Flake8| delegated check running to pep8. In 3.0 |Flake8|
-on that responsibility. This has allowed for simpler
+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
+created for *each* file to be analyzed by |Flake8|. Each instance, has a copy
-all of the plugins registered with setuptools in the ``flake8.extension``
+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
@@ -22,8 +22,8 @@ excluded.
 Processing Files
 ----------------
 
-Unfortunately, since Flake8 took over check running from pep8/pycodestyle, it
+Unfortunately, since |Flake8| took over check running from pep8/pycodestyle,
-also had to take over parsing and processing files for the checkers
+it 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

docs/source/internal/cli.rst

@@ -1,7 +1,7 @@
 Command Line Interface
 ======================
 
-The command line interface of Flake8 is modeled as an application via
+The command line interface of |Flake8| is modeled as an application via
 :class:`~flake8.main.cli.Application`. When a user runs ``flake8`` at their
 command line, :func:`~flake8.main.cli.main` is run which handles
 management of the application.
@@ -10,7 +10,7 @@ User input is parsed *twice* to accomodate logging and verbosity options
 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
+The default |Flake8| options are registered by
 :func:`~flake8.main.options.register_default_options`. Trying to register
 these options in plugins will result in errors.
 

docs/source/internal/contributing.rst

@@ -2,7 +2,7 @@
  Contributing to Flake8
 ========================
 
-There are many ways to contriubte to Flake8, and we encourage them all:
+There are many ways to contriubte to |Flake8|, and we encourage them all:
 
 - contributing bug reports and feature requests
 
@@ -18,7 +18,7 @@ reassure you that any help you can provide *is* valuable.
 Code of Conduct
 ===============
 
-Flake8 adheres to the `Python Code Quality Authority's Code of Conduct`_.
+|Flake8| adheres to the `Python Code Quality Authority's Code of Conduct`_.
 Any violations of the Code of Conduct should be reported to Ian Cordasco
 (graffatcolmingov [at] gmail [dot] com).
 
@@ -26,7 +26,7 @@ Any violations of the Code of Conduct should be reported to Ian Cordasco
 Setting Up A Development Environment
 ====================================
 
-To contribute to Flake8's development, you simply need:
+To contribute to |Flake8|'s development, you simply need:
 
 - Python (one of the versions we support)
 
@@ -50,29 +50,29 @@ To contribute to Flake8's development, you simply need:
 Filing a Bug
 ============
 
-When filing a bug against Flake8, please fill out the issue template as it is
+When filing a bug against |Flake8|, please fill out the issue template as it
-provided to you by `GitLab`_. If your bug is in reference to one of the
+is provided to you by `GitLab`_. If your bug is in reference to one of the
-checks that Flake8 reports by default, please do not report them to Flake8
+checks that |Flake8| reports by default, please do not report them to |Flake8|
-unless Flake8 is doing something to prevent the check from running or you
+unless |Flake8| is doing something to prevent the check from running or you
-have some reason to believe Flake8 is inhibiting the effectiveness of the
+have some reason to believe |Flake8| is inhibiting the effectiveness of the
 check.
 
 **Please search for closed and open bug reports before opening new ones.**
 
 All bug reports about checks should go to their respective projects:
 
-- Check codes starting with ``E`` and ``W`` should be reported to
+- Error codes starting with ``E`` and ``W`` should be reported to
   `pycodestyle`_.
 
-- Check codes starting with ``F`` should be reported to `pyflakes`_
+- Error codes starting with ``F`` should be reported to `pyflakes`_
 
-- Check codes starting with ``C`` should be reported to `mccabe`_
+- Error codes starting with ``C`` should be reported to `mccabe`_
 
 
 Requesting a New Feature
 ========================
 
-When requesting a new feature in Flake8, please fill out the issue template.
+When requesting a new feature in |Flake8|, please fill out the issue template.
 Please also note if there are any existing alternatives to your new feature
 either via plugins, or combining command-line options. Please provide example
 use cases. For example, do not ask for a feature like this:
@@ -81,8 +81,8 @@ use cases. For example, do not ask for a feature like this:
 
 Instead ask:
 
-    I need Flake8 to frobulate these files because my team expects them to
+    I need |Flake8| to frobulate these files because my team expects them to
-    frobulated but Flake8 currently does not frobulate them. We tried using
+    frobulated but |Flake8| currently does not frobulate them. We tried using
     ``--filename`` but we could not create a pattern that worked.
 
 The more you explain about *why* you need a feature, the more likely we are to
@@ -92,11 +92,11 @@ understand your needs and help you to the best of our ability.
 Contributing Documentation
 ==========================
 
-To contribute to Flake8's documentation, you should first familiarize yourself
+To contribute to |Flake8|'s documentation, you might want to first read a
-with reStructuredText and Sphinx. For the most part, you should be fine
+little about reStructuredText or Sphinx. For the most part, you should be fine
-following the structure and style of the rest of Flake8's documentation.
+following the structure and style of the rest of |Flake8|'s documentation.
 
-All of Flake8's documentation is written in reStructuredText and rendered by
+All of |Flake8|'s documentation is written in reStructuredText and rendered by
 Sphinx. The source (reStructuredText) lives in ``docs/source/``. To build
 the documentation the way our Continuous Integration does, run:
 
@@ -129,7 +129,7 @@ documentation generation and refresh the documentation you're working on.
 Contributing Code
 =================
 
-Flake8 development happens on `GitLab`_. Code contributions should be
+|Flake8| development happens on `GitLab`_. Code contributions should be
 submitted there.
 
 Merge requests should:
@@ -170,12 +170,12 @@ When reviewing other people's merge requests and issues, please be
 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
-appropriate for Flake8.
+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. This provides
+|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

@@ -2,12 +2,12 @@
  Built-in Formatters
 =====================
 
-By default Flake8 has two formatters built-in, ``default`` and ``pylint``.
+By default |Flake8| has two formatters built-in, ``default`` and ``pylint``.
 These correspond to two classes |DefaultFormatter| and |PylintFormatter|.
 
-In Flake8 2.0, pep8 handled formatting of errors and also allowed users to
+In |Flake8| 2.0, pep8 handled formatting of errors and also allowed users to
 specify an arbitrary format string as a parameter to ``--format``. In order
-to allow for this backwards compatibility, Flake8 3.0 made two choices:
+to allow for this backwards compatibility, |Flake8| 3.0 made two choices:
 
 #. To not limit a user's choices for ``--format`` to the format class names
 

docs/source/internal/index.rst

@@ -2,7 +2,7 @@
  Exploring Flake8's Internals
 ==============================
 
-While writing Flake8 3.0, the developers attempted to capture some reasoning
+While writing |Flake8| 3.0, the developers attempted to capture some reasoning
 and decision information in internal documentation meant for future developers
 and maintaners. Most of this information is unnecessary for users and plugin
 developers. Some of it, however, is linked to from the plugin development

docs/source/internal/option_handling.rst

@@ -4,12 +4,12 @@ Option and Configuration Handling
 Option Management
 -----------------
 
-Command-line options are often also set in configuration files for Flake8.
+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 well as
 most plugin options.
 
-In Flake8 2, plugins received a :class:`optparse.OptionParser` instance and
+In |Flake8| 2, plugins received a :class:`optparse.OptionParser` instance and
 called :meth:`optparse.OptionParser.add_option` to register options. If the
 plugin author also wanted to have that option parsed from config files they
 also had to do something like:
@@ -22,13 +22,13 @@ also had to do something like:
 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
+Since |Flake8| 3 was rewritten from scratch, we decided to take a different
 approach to configuration file parsing. Instead of needing to know about an
-undocumented attribute that pep8 looks for, Flake8 3 now accepts a parameter
+undocumented attribute that pep8 looks for, |Flake8| 3 now accepts a parameter
 to ``add_option``, specifically ``parse_from_config`` which is a boolean
 value.
 
-Flake8 does this by creating its own abstractions on top of :mod:`optparse`.
+|Flake8| does this by creating its own abstractions on top of :mod:`optparse`.
 The first abstraction is the :class:`flake8.options.manager.Option` class. The
 second is the :class:`flake8.options.manager.OptionManager`. In fact, we add
 three new parameters:
@@ -49,14 +49,22 @@ example, let's consider a user's list of ignored error codes for a project:
 
     [flake8]
     ignore =
-        E111,  # Reasoning
+        # Reasoning
-        E711,  # Reasoning
+        E111,
-        E712,  # Reasoning
+        # Reasoning
-        E121,  # Reasoning
+        E711,
-        E122,  # Reasoning
+        # Reasoning
-        E123,  # Reasoning
+        E712,
-        E131,  # Reasoning
+        # Reasoning
-        E251   # Reasoning
+        E121,
+        # Reasoning
+        E122,
+        # Reasoning
+        E123,
+        # Reasoning
+        E131,
+        # Reasoning
+        E251
 
 It makes sense here to allow users to specify the value this way, but, the
 standard libary's :class:`configparser.RawConfigParser` class does returns a
@@ -67,8 +75,8 @@ string that looks like
     "\nE111,  \nE711,  \nE712,  \nE121,  \nE122,  \nE123,  \nE131,  \nE251  "
 
 This means that a typical call to :meth:`str.split` with ``','`` will not be
-sufficient here. Telling Flake8 that something is a comma-separated list
+sufficient here. Telling |Flake8| that something is a comma-separated list
-(e.g., ``comma_separated_list=True``) will handle this for you. Flake8 will
+(e.g., ``comma_separated_list=True``) will handle this for you. |Flake8| will
 return:
 
 .. code-block:: python
@@ -117,10 +125,11 @@ extra arguments we highlighted above.
 Configuration File Management
 -----------------------------
 
-In Flake8 2, configuration file discovery and management was handled by pep8.
+In |Flake8| 2, configuration file discovery and management was handled by
-In pep8's 1.6 release series, it drastically broke how discovery and merging
+pep8.  In pep8's 1.6 release series, it drastically broke how discovery and
-worked (as a result of trying to improve it). To avoid a dependency breaking
+merging worked (as a result of trying to improve it). To avoid a dependency
-Flake8 again in the future, we have created our own discovery and management.
+breaking |Flake8| again in the future, we have created our own discovery and
+management.
 As part of managing this ourselves, we decided to change management/discovery
 for 3.0.0. We have done the following:
 
@@ -137,7 +146,7 @@ for 3.0.0. We have done the following:
   take precedence over user and project files.
 
 - **New in 3.0.0** The user can specify ``--config <path-to-file>`` to so this
-  file is the only configuration file used. This is a change from Flake8 2
+  file is the only configuration file used. This is a change from |Flake8| 2
   where pep8 would simply merge this configuration file into the configuration
   generated by user and project files (where this takes precedence).
 
@@ -148,10 +157,10 @@ To facilitate the configuration file management, we've taken a different
 approach to discovery and management of files than pep8. In pep8 1.5, 1.6, and
 1.7 configuration discovery and management was centralized in `66 lines of
 very terse python`_ which was confusing and not very explicit. The terseness
-of this function (Flake8's authors believe) caused the confusion and problems
+of this function (|Flake8|'s authors believe) caused the confusion and
-with pep8's 1.6 series. As such, Flake8 has separated out discovery,
+problems with pep8's 1.6 series. As such, |Flake8| has separated out
-management, and merging into a module to make reasoning about each of these
+discovery, management, and merging into a module to make reasoning about each
-pieces easier and more explicit (as well as easier to test).
+of these pieces easier and more explicit (as well as easier to test).
 
 Configuration file discovery is managed by the
 :class:`~flake8.options.config.ConfigFileFinder` object. This object needs to

docs/source/internal/plugin_handling.rst

@@ -4,8 +4,8 @@ Plugin Handling
 Plugin Management
 -----------------
 
-Flake8 3.0 added support for two other plugins besides those which define new
+|Flake8| 3.0 added support for two other plugins besides those which define
-checks. It now supports:
+new checks. It now supports:
 
 - extra checks
 
@@ -13,7 +13,7 @@ checks. It now supports:
 
 - listeners to auto-correct violations of checks
 
-To facilitate this, Flake8 needed a more mature way of managing plugins.
+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.
@@ -72,21 +72,21 @@ existing packages on PyPI allowed for storing data on each node of the trie,
 it was left up to write our own as :class:`~flake8.plugins._trie.Trie`. On
 top of that we layer our :class:`~flake8.plugins.notifier.Notifier` class.
 
-Now when Flake8 receives an error or warning, we can easily call the
+Now when |Flake8| receives an error or warning, we can easily call the
 :meth:`~flake8.plugins.notifier.Notifier.notify` method and let plugins act on
 that knowledge.
 
 Default Plugins
 ---------------
 
-Finally, Flake8 has always provided its own plugin shim for Pyflakes. As part
+Finally, |Flake8| has always provided its own plugin shim for Pyflakes. As
-of that we carry our own shim in-tree and now store that in
+part of that we carry our own shim in-tree and now store that in
 :mod:`flake8.plugins.pyflakes`.
 
-Flake8 also registers plugins for pep8. Each check in pep8 requires different
+|Flake8| also registers plugins for pep8. Each check in pep8 requires
-parameters and it cannot easily be shimmed together like Pyflakes was. As
+different parameters and it cannot easily be shimmed together like Pyflakes
-such, plugins have a concept of a "group". If you look at our :file:`setup.py`
+was. As such, plugins have a concept of a "group". If you look at our
-you will see that we register pep8 checks roughly like so:
+:file:`setup.py` you will see that we register pep8 checks roughly like so:
 
 .. code::
 

docs/source/internal/utils.rst

@@ -2,7 +2,7 @@
  Utility Functions
 ===================
 
-Flake8 has a few utility functions that it uses internally.
+|Flake8| has a few utility functions that it uses internally.
 
 .. warning::
 
@@ -39,8 +39,8 @@ And converts it to a list that looks as follows
 
     ["E121", "W123", "F904"]
 
-This function helps normalize any kind of comma-separated input you or Flake8
+This function helps normalize any kind of comma-separated input you or |Flake8|
-might receive. This is most helpful when taking advantage of Flake8's
+might receive. This is most helpful when taking advantage of |Flake8|'s
 additional parameters to :class:`~flake8.options.manager.Option`.
 
 .. autofunction:: flake8.utils.normalize_path
@@ -74,11 +74,11 @@ Python we're using can actually use multiprocessing on Windows.
 
 Another helpful function that is named only to be explicit given it is a very
 trivial check, this checks if the user specified ``-`` in their arguments to
-Flake8 to indicate we should read from stdin.
+|Flake8| to indicate we should read from stdin.
 
 .. autofunction:: flake8.utils.filenames_from
 
-When provided an argument to Flake8, we need to be able to traverse
+When provided an argument to |Flake8|, we need to be able to traverse
 directories in a convenient manner. For example, if someone runs
 
 .. code::
@@ -103,7 +103,7 @@ function abstracts that logic away with a little extra logic.
 
 .. autofunction:: flake8.utils.parameters_for
 
-Flake8 analyzes the parameters to plugins to determine what input they are
+|Flake8| analyzes the parameters to plugins to determine what input they are
 expecting. Plugins may expect one of the following:
 
 - ``physical_line`` to receive the line as it appears in the file
@@ -120,7 +120,7 @@ argument so we can check the parameters of the plugin consistently.
 
 .. autofunction:: flake8.utils.parse_unified_diff
 
-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

@@ -4,7 +4,7 @@
  Configuring Flake8
 ====================
 
-Once you have learned how to :ref:`invoke <invocation>` Flake8, you will soon
+Once you have learned how to :ref:`invoke <invocation>` |Flake8|, you will soon
 want to learn how to configure it so you do not have to specify the same
 options every time you use it.
 
@@ -24,7 +24,7 @@ Remember that you want to specify certain options without writing
 Configuration Locations
 =======================
 
-Flake8 supports storing its configuration in the following places:
+|Flake8| supports storing its configuration in the following places:
 
 - Your top-level user directory
 
@@ -34,7 +34,7 @@ Flake8 supports storing its configuration in the following places:
 "User" Configuration
 --------------------
 
-Flake8 allows a user to use "global" configuration file to store preferences.
+|Flake8| allows a user to use "global" configuration file to store preferences.
 The user configuration file is expected to be stored somewhere in the user's
 "home" directory.
 
@@ -44,7 +44,7 @@ The user configuration file is expected to be stored somewhere in the user's
 - On Linux and other Unix like systems (including OS X) we will look in
   ``~/``.
 
-Note that Flake8 looks for ``~\.flake8`` on Windows and ``~/.config/flake8``
+Note that |Flake8| looks for ``~\.flake8`` on Windows and ``~/.config/flake8``
 on Linux and other Unix systems.
 
 User configuration files use the same syntax as Project Configuration files.
@@ -54,8 +54,8 @@ Keep reading to see that syntax.
 Project Configuration
 ---------------------
 
-Flake8 is written with the understanding that people organize projects into
+|Flake8| is written with the understanding that people organize projects into
-sub-directories. Let's take for example Flake8's own project structure
+sub-directories. Let's take for example |Flake8|'s own project structure
 
 .. code::
 
@@ -81,10 +81,10 @@ sub-directories. Let's take for example Flake8's own project structure
 
 In the top-level ``flake8`` directory (which contains ``docs``, ``flake8``,
 and ``tests``) there's also ``tox.ini`` and ``setup.cfg`` files. In our case,
-we keep our Flake8 configuration in ``tox.ini``. Regardless of whether you
+we keep our |Flake8| configuration in ``tox.ini``. Regardless of whether you
 keep your config in ``.flake8``, ``setup.cfg``, or ``tox.ini`` we expect you
-to use INI to configure Flake8 (since each of these files already uses INI
+to use INI to configure |Flake8| (since each of these files already uses INI
-as a format). This means that any Flake8 configuration you wish to set needs
+as a format). This means that any |Flake8| configuration you wish to set needs
 to be in the ``flake8`` section, which means it needs to start like so:
 
 .. code-block:: ini
@@ -100,11 +100,11 @@ be named in either of two ways:
 
 .. note::
 
-    Not every Flake8 command-line option can be specified in the configuration
+    Not every |Flake8| command-line option can be specified in the
-    file. See :ref:`our list of options <options-list>` to determine which
+    configuration file. See :ref:`our list of options <options-list>` to
-    options will be parsed from the configuration files.
+    determine which options will be parsed from the configuration files.
 
-Let's actually look at Flake8's own configuration section:
+Let's actually look at |Flake8|'s own configuration section:
 
 .. code-block:: ini
 
@@ -163,14 +163,14 @@ 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 to Flake8.
+    Please do **not** open issues about this dependency to |Flake8|.
 
 .. note::
 
     You can also specify ``--max-complexity`` as ``max_complexity = 10``.
 
 This is also useful if you have a long list of error codes to ignore. Let's
-look at a portion of OpenStack's Swift project configuration:
+look at a portion of OpenStack's Swift `project configuration`_:
 
 .. code-block:: ini
 
@@ -220,5 +220,8 @@ They use the comments to describe the check but they could also write this as:
         H501
 
 Or they could use each comment to describe **why** they've ignored the check.
-:program:`Flake8` knows how to parse these lists and will appropriatey handle
+|Flake8| knows how to parse these lists and will appropriatey handle
 these situations.
+
+.. _project configuration:
+    https://github.com/openstack/swift/blob/3944d820387f08372c1a29444f4af7d8e6090ae9/tox.ini#L66..L81

docs/source/user/ignoring-errors.rst

@@ -55,7 +55,7 @@ then those will be reported.
 
 .. note::
 
-    If we ever want to disable Flake8 respecting ``# noqa`` comments, we can
+    If we ever want to disable |Flake8| respecting ``# noqa`` comments, we can
     can refer to :option:`flake8 --disable-noqa`.
 
 If we instead had more than one error that we wished to ignore, we could
@@ -84,11 +84,7 @@ file:
 
 The former is the **recommended** way of ignoring entire files. By using our
 exclude list, we can include it in our configuration file and have one central
-place to find what files aren't included in Flake8 checks. The latter has the
+place to find what files aren't included in |Flake8| checks. The latter has the
 benefit that when we run |Flake8| with :option:`flake8 --disable-noqa` all of
 the errors in that file will show up without having to modify our
 configuration. Both exist so we can choose which is better for us.
-
-
-.. replacements
-.. |Flake8| replace:: :program:`Flake8`

docs/source/user/index.rst

@@ -2,7 +2,7 @@
  Using Flake8
 ==============
 
-Flake8 can be used in many ways. A few:
+|Flake8| can be used in many ways. A few:
 
 - invoked on the command-line
 
@@ -10,12 +10,12 @@ Flake8 can be used in many ways. A few:
 
 - called by Git or Mercurial on or around committing
 
-This guide will cover all of these and the nuances for using Flake8.
+This guide will cover all of these and the nuances for using |Flake8|.
 
 .. note::
 
-    This portion of Flake8's documentation does not cover installation. See
+    This portion of |Flake8|'s documentation does not cover installation. See
-    the :ref:`installation-guide` section for how to install Flake8.
+    the :ref:`installation-guide` section for how to install |Flake8|.
 
 .. toctree::
     :maxdepth: 2

docs/source/user/invocation.rst

@@ -4,16 +4,16 @@
  Invoking Flake8
 =================
 
-Once you have :ref:`installed <installation-guide>` Flake8, you can begin
+Once you have :ref:`installed <installation-guide>` |Flake8|, you can begin
-using it. Most of the time, you will be able to generically invoke Flake8
+using it. Most of the time, you will be able to generically invoke |Flake8|
 like so:
 
 .. prompt:: bash
 
     flake8 ...
 
-Where you simply allow the shell running in your terminal to locate Flake8.
+Where you simply allow the shell running in your terminal to locate |Flake8|.
-In some cases, though, you may have installed Flake8 for multiple versions
+In some cases, though, you may have installed |Flake8| for multiple versions
 of Python (e.g., Python 2.7 and Python 3.5) and you need to call a specific
 version. In that case, you will have much better results using:
 
@@ -27,15 +27,15 @@ Or
 
     python3.5 -m flake8
 
-Since that will tell the correct version of Python to run Flake8.
+Since that will tell the correct version of Python to run |Flake8|.
 
 .. note::
 
-    Installing Flake8 once will not install it on both Python 2.7 and
+    Installing |Flake8| once will not install it on both Python 2.7 and
     Python 3.5. It will only install it for the version of Python that
     is running pip.
 
-It is also possible to specify command-line options directly to Flake8:
+It is also possible to specify command-line options directly to |Flake8|:
 
 .. prompt:: bash
 
@@ -53,7 +53,7 @@ Or
     From now on, we'll simply use ``flake8`` and assume that the user
     knows they can instead use ``python<version> -m flake8`` instead.
 
-It's also possible to narrow what Flake8 will try to check by specifying
+It's also possible to narrow what |Flake8| will try to check by specifying
 exactly the paths and directories you want it to check. Let's assume that
 we have a directory with python files and subdirectories which have python
 files (and may have more sub-directories) called ``my_project``. Then if

docs/source/user/options.rst

@@ -29,7 +29,7 @@
 
 .. option:: --version
 
-    Show :program:`Flake8`\ 's version as well as the versions of all plugins
+    Show |Flake8|'s version as well as the versions of all plugins
     installed.
 
     Command-line usage:
@@ -43,7 +43,7 @@
 
 .. option:: -h, --help
 
-    Show a description of how to use :program:`Flake8` and its options.
+    Show a description of how to use |Flake8| and its options.
 
     Command-line usage:
 
@@ -57,7 +57,7 @@
 
 .. option::  -v, --verbose
 
-    Increase the verbosity of Flake8's output. Each time you specify
+    Increase the verbosity of |Flake8|'s output. Each time you specify
     it, it will print more and more information.
 
     Command-line example:
@@ -77,7 +77,7 @@
 
 .. option:: -q, --quiet
 
-    Decrease the verbosity of Flake8's output. Each time you specify it,
+    Decrease the verbosity of |Flake8|'s output. Each time you specify it,
     it will print less and less information.
 
     Command-line example:
@@ -286,7 +286,7 @@
 
     Specify a list of codes to ignore. The list is expected to be
     comma-separated, and does not need to specify an error code exactly.
-    Since Flake8 3.0, this **can** be combined with :option:`--select`. See
+    Since |Flake8| 3.0, this **can** be combined with :option:`--select`. See
     :option:`--select` for more information.
 
     For example, if you wish to only ignore ``W234``, then you can specify
@@ -349,7 +349,7 @@
 
 .. option:: --select=<errors>
 
-    Specify the list of error codes you wish Flake8 to report. Similarly to
+    Specify the list of error codes you wish |Flake8| to report. Similarly to
     :option:`--ignore`. You can specify a portion of an error code to get all
     that start with that string. For example, you can use ``E``, ``E4``,
     ``E43``, and ``E431``.
@@ -370,7 +370,7 @@
         flake8 --select=E --ignore=E432 dir/
 
     This will report all codes that start with ``E``, but ignore ``E432``
-    specifically. This is more flexibly than the Flake8 2.x and 1.x used
+    specifically. This is more flexibly than the |Flake8| 2.x and 1.x used
     to be.
 
     This **can** be specified in config files.
@@ -453,7 +453,7 @@
 
     Enable off-by-default extensions.
 
-    Plugins to Flake8 have the option of registering themselves as
+    Plugins to |Flake8| have the option of registering themselves as
     off-by-default. These plugins effectively add themselves to the
     default ignore list.
 
@@ -479,9 +479,9 @@
 
 .. option:: --exit-zero
 
-    Force Flake8 to use the exit status code 0 even if there are errors.
+    Force |Flake8| to use the exit status code 0 even if there are errors.
 
-    By default Flake8 will exit with a non-zero integer if there are errors.
+    By default |Flake8| will exit with a non-zero integer if there are errors.
 
     Command-line example:
 
@@ -514,7 +514,7 @@
 
 .. option:: --jobs=<n>
 
-    Specify the number of subprocesses that Flake8 will use to run checks in
+    Specify the number of subprocesses that |Flake8| will use to run checks in
     parallel.
 
     .. note::
@@ -566,7 +566,7 @@
 .. option:: --append-config=<config>
 
     Provide extra config files to parse in after and in addition to the files
-    that Flake8 found on its own. Since these files are the last ones read
+    that |Flake8| found on its own. Since these files are the last ones read
     into the Configuration Parser, so it has the highest precedence if it
     provides an option specified in another config file.
 
@@ -582,7 +582,8 @@
 .. option:: --config=<config>
 
     Provide a path to a config file that will be the only config file read and
-    used. This will cause Flake8 to ignore all other config files that exist.
+    used. This will cause |Flake8| to ignore all other config files that
+    exist.
 
     Command-line example:
 
@@ -595,7 +596,7 @@
 
 .. option:: --isolated
 
-    Ignore any config files and use Flake8 as if there were no config files
+    Ignore any config files and use |Flake8| as if there were no config files
     found.
 
     Command-line example:
@@ -710,7 +711,7 @@
 
 .. option:: --benchmark
 
-    Collect and print benchmarks for this run of Flake8. This aggregates the
+    Collect and print benchmarks for this run of |Flake8|. This aggregates the
     total number of:
 
     - tokens

docs/source/user/python-api.rst

@@ -2,7 +2,7 @@
  Public Python API
 ===================
 
-Flake8 3.0.0 presently does not have a public, stable Python API.
+|Flake8| 3.0.0 presently does not have a public, stable Python API.
 
 When it does it will be located in :mod:`flake8.api` and that will
 be documented here.