Start writing new documentation around --select

In order to write this documentation, we need to also add documentation
for the --max-complexity option which was heretofore undocumented.

4 files changed, 293 insertions, 91 deletions

diff --git a/docs/source/user/ignoring-errors.rst b/docs/source/user/ignoring-errors.rst
deleted file mode 100644
index ff37c4a..0000000
--- a/docs/source/user/ignoring-errors.rst
+++ /dev/null
@@ -1,90 +0,0 @@
-=============================
- Ignoring Errors with Flake8
-=============================
-
-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 see the default list, :option:`flake8 --help` will
-show the output with the current default list.
-
-
-Changing the Ignore List
-========================
-
-If we want to change the list of ignored codes for a single run, we can use
-:option:`flake8 --ignore` to specify a comma-separated list of codes for a
-specific run on the command-line, e.g.,
-
-.. prompt:: bash
-
-    flake8 --ignore=E1,E23,W503 path/to/files/ path/to/more/files/
-
-This tells |Flake8| to ignore any error codes starting with ``E1``, ``E23``,
-or ``W503`` while it is running.
-
-.. note::
-
-    The documentation for :option:`flake8 --ignore` shows examples for how
-    to change the ignore list in the configuration file. See also
-    :ref:`configuration` as well for details about how to use configuration
-    files.
-
-
-In-line Ignoring Errors
-=======================
-
-In some cases, we might not want to ignore an error code (or class of error
-codes) for the entirety of our project. Instead, we might want to ignore the
-specific error code on a specific line. Let's take for example a line like
-
-.. code-block:: python
-
-    example = lambda: 'example'
-
-Sometimes we genuinely need something this simple. We could instead define
-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
-
-    example = lambda: 'example'  # noqa: E731
-
-This will only ignore the error from pycodestyle that checks for lambda
-assignments and generates an ``E731``. If there are other errors on the line
-then those will be reported.
-
-.. note::
-
-    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
-list all of the errors with commas separating them:
-
-.. code-block:: python
-
-    # noqa: E731,E123
-
-Finally, if we have a particularly bad line of code, we can ignore every error
-using simply ``# noqa`` with nothing after it.
-
-
-Ignoring Entire Files
-=====================
-
-Imagine a situation where we are adding |Flake8| to a codebase. Let's further
-imagine that with the exception of a few particularly bad files, we can add
-|Flake8| easily and move on with our lives. There are two ways to ignore the
-file:
-
-#. By explicitly adding it to our list of excluded paths (see: :option:`flake8
-   --exclude`)
-
-#. By adding ``# flake8: noqa`` to the 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
-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.
diff --git a/docs/source/user/index.rst b/docs/source/user/index.rst
index e0f9108..5a24b21 100644
--- a/docs/source/user/index.rst
+++ b/docs/source/user/index.rst
@@ -24,7 +24,7 @@ This guide will cover all of these and the nuances for using |Flake8|.
     configuration
     options
     error-codes
-    ignoring-errors
+    violations
     using-plugins
     using-hooks
     python-api
diff --git a/docs/source/user/options.rst b/docs/source/user/options.rst
index 6252c09..856fbf7 100644
--- a/docs/source/user/options.rst
+++ b/docs/source/user/options.rst
@@ -796,3 +796,24 @@
         }
 
     This **can not** be specified in config files.
+
+
+.. option:: --max-complexity=<n>
+
+    Set the maximum allowed McCabe complexity value for a block of code.
+
+    This option is provided by the ``mccabe`` dependency's |Flake8| plugin.
+
+    Command-line usage:
+
+    .. prompt:: bash
+
+        flake8 --max-complexity 15 dir/
+
+    This **can** be specified in config files.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        max-complexity = 15
diff --git a/docs/source/user/violations.rst b/docs/source/user/violations.rst
new file mode 100644
index 0000000..ed44c94
--- /dev/null
+++ b/docs/source/user/violations.rst
@@ -0,0 +1,271 @@
+===================================
+ Selecting and Ignoring Violations
+===================================
+
+It is possible to select and ignore certain violations reported by |Flake8|
+and the plugins we've installed. It's also possible as of |Flake8| 3.0 to
+combine usage of :option:`flake8 --select` and :option:`flake8 --ignore`. This
+chapter of the User Guide aims to educate about how Flake8 will report errors
+based on different inputs.
+
+
+
+Ignoring Violations with Flake8
+===============================
+
+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 see the default list, :option:`flake8 --help` will
+show the output with the current default list.
+
+
+Changing the Ignore List
+------------------------
+
+If we want to change the list of ignored codes for a single run, we can use
+:option:`flake8 --ignore` to specify a comma-separated list of codes for a
+specific run on the command-line, e.g.,
+
+.. prompt:: bash
+
+    flake8 --ignore=E1,E23,W503 path/to/files/ path/to/more/files/
+
+This tells |Flake8| to ignore any error codes starting with ``E1``, ``E23``,
+or ``W503`` while it is running.
+
+.. note::
+
+    The documentation for :option:`flake8 --ignore` shows examples for how
+    to change the ignore list in the configuration file. See also
+    :ref:`configuration` as well for details about how to use configuration
+    files.
+
+
+In-line Ignoring Errors
+-----------------------
+
+In some cases, we might not want to ignore an error code (or class of error
+codes) for the entirety of our project. Instead, we might want to ignore the
+specific error code on a specific line. Let's take for example a line like
+
+.. code-block:: python
+
+    example = lambda: 'example'
+
+Sometimes we genuinely need something this simple. We could instead define
+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
+
+    example = lambda: 'example'  # noqa: E731
+
+This will only ignore the error from pycodestyle that checks for lambda
+assignments and generates an ``E731``. If there are other errors on the line
+then those will be reported.
+
+.. note::
+
+    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
+list all of the errors with commas separating them:
+
+.. code-block:: python
+
+    # noqa: E731,E123
+
+Finally, if we have a particularly bad line of code, we can ignore every error
+using simply ``# noqa`` with nothing after it.
+
+
+Ignoring Entire Files
+---------------------
+
+Imagine a situation where we are adding |Flake8| to a codebase. Let's further
+imagine that with the exception of a few particularly bad files, we can add
+|Flake8| easily and move on with our lives. There are two ways to ignore the
+file:
+
+#. By explicitly adding it to our list of excluded paths (see: :option:`flake8
+   --exclude`)
+
+#. By adding ``# flake8: noqa`` to the 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
+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.
+
+
+
+Selecting Violations with Flake8
+================================
+
+|Flake8| has a default list of violation classes that we use. This list is:
+
+- ``C90``
+
+  All ``C90`` class violations are reported when the user specifies
+  :option:`flake8 --max-complexity`
+
+- ``E``
+
+  All ``E`` class violations are "errors" reported by pycodestyle
+
+- ``F``
+
+  All ``F`` class violations are reported by pyflakes
+
+- ``W``
+
+  All ``W`` class violations are "warnings" reported by pycodestyle
+
+This list can be overridden by specifying :option:`flake8 --select`. Just as
+specifying :option:`flake8 --ignore` will change the behaviour of |Flake8|, so
+will :option:`flake8 --select`.
+
+Let's look through some examples using this sample code:
+
+.. code-block:: python
+
+    # example.py
+    def foo():
+        print(
+                    "Hello"
+            "World"
+            )
+
+By default, if we run ``flake8`` on this file we'll get:
+
+.. prompt:: bash
+
+    flake8 example.py
+
+.. code:: text
+
+    example.py:4:9: E131 continuation line unaligned for hanging indent
+
+Now let's select all ``E`` class violations:
+
+.. prompt:: bash
+
+    flake8 --select E example.py
+
+.. code:: text
+
+    example.py:3:17: E126 continuation line over-indented for hanging indent
+    example.py:4:9: E131 continuation line unaligned for hanging indent
+    example.py:5:9: E121 continuation line under-indented for hanging indent
+
+Suddenly we now have far more erors that are reported to us. Using
+``--select`` alone will override the default ``--ignore`` list. In these cases,
+the user is telling us that they want all ``E`` violations and so we ignore
+our list of violations that we ignore by default.
+
+We can also be highly specific. For example, we can do
+
+.. prompt:: bash
+
+    flake8 --select E121 example.py
+
+.. code:: text
+
+    example.py:5:9: E121 continuation line under-indented for hanging indent
+
+We can also specify lists of items to select both on the command-line and in
+our configuration files.
+
+.. prompt:: bash
+
+    flake8 --select E121,E131 example.py
+
+.. code:: text
+
+    example.py:4:9: E131 continuation line unaligned for hanging indent
+    example.py:5:9: E121 continuation line under-indented for hanging indent
+
+
+
+Selecting and Ignoring Simultaneously For Fun and Profit
+========================================================
+
+Prior to |Flake8| 3.0, all handling of :option:`flake8 --select` and
+:option:`flake8 --ignore` was delegated to pycodestyle. It's handling of the
+options significantly differs from how |Flake8| 3.0 has been designed.
+
+pycodestyle has always preferred ``--ignore`` over ``--select`` and will
+ignore ``--select`` if the user provides both. |Flake8| 3.0 will now do its
+best to intuitively combine both options provided by the user. Let's look at
+some examples using:
+
+.. code-block:: python
+
+    # example.py
+    import os
+
+
+    def foo():
+        var = 1
+        print(
+                    "Hello"
+            "World"
+            )
+
+If we run |Flake8| with its default settings we get:
+
+.. prompt:: bash
+
+    flake8 example.py
+
+.. code:: text
+
+    example.py:1:1: F401 'os' imported but unused
+    example.py:5:5: F841 local variable 'var' is assigned to but never used
+    example.py:8:9: E131 continuation line unaligned for hanging indent
+
+Now let's select all ``E`` and ``F`` violations including those in the default
+ignore list.
+
+.. prompt:: bash
+
+    flake8 --select E,F example.py
+
+.. code:: text
+
+    example.py:1:1: F401 'os' imported but unused
+    example.py:5:5: F841 local variable 'var' is assigned to but never used
+    example.py:7:17: E126 continuation line over-indented for hanging indent
+    example.py:8:9: E131 continuation line unaligned for hanging indent
+    example.py:9:9: E121 continuation line under-indented for hanging indent
+
+Now let's selectively ignore some of these while selecting the rest:
+
+.. prompt:: bash
+
+    flake8 --select E,F --ignore F401,E121 example.py
+
+.. code:: text
+
+    example.py:5:5: F841 local variable 'var' is assigned to but never used
+    example.py:7:17: E126 continuation line over-indented for hanging indent
+    example.py:8:9: E131 continuation line unaligned for hanging indent
+
+Via this example, we can see that the *most specific* **user-specified** rule
+will win. So in the above, we had very vague select rules and two very
+specific ignore rules. Let's look at a different example:
+
+.. prompt:: bash
+
+    flake8 --select F401,E131 --ignore E,F example.py
+
+.. code:: text
+
+    example.py:1:1: F401 'os' imported but unused
+    example.py:8:9: E131 continuation line unaligned for hanging indent
+
+In this case, we see that since our selected violation codes were more
+specific those were reported.