Add a first pass at documenting cli options

docs/source/user/options.rst

@@ -4,87 +4,626 @@
  Full Listing of Options and Their Descriptions
 ================================================
 
-..
+.. program:: flake8
-      -v, --verbose         Print more information about what is happening in
-                            flake8. This option is repeatable and will increase
-                            verbosity each time it is repeated.
-      -q, --quiet           Report only file names, or nothing. This option is
-                            repeatable.
-      --count               Print total number of errors and warnings to standard
-                            error and set the exit code to 1 if total is not
-                            empty.
-      --diff                Report changes only within line number ranges in the
-                            unified diff provided on standard in by the user.
-      --exclude=patterns    Comma-separated list of files or directories to
-                            exclude.(Default:
-                            .svn,CVS,.bzr,.hg,.git,__pycache__,.tox)
-      --filename=patterns   Only check for filenames matching the patterns in this
-                            comma-separated list. (Default: *.py)
-      --format=format       Format errors according to the chosen formatter.
-      --hang-closing        Hang closing bracket instead of matching indentation
-                            of opening bracket's line.
-      --ignore=errors       Comma-separated list of errors and warnings to ignore
-                            (or skip). For example, ``--ignore=E4,E51,W234``.
-                            (Default: E121,E123,E126,E226,E24,E704)
-      --max-line-length=n   Maximum allowed line length for the entirety of this
-                            run. (Default: 79)
-      --select=errors       Comma-separated list of errors and warnings to enable.
-                            For example, ``--select=E4,E51,W234``. (Default: )
-      --disable-noqa        Disable the effect of "# noqa". This will report
-                            errors on lines with "# noqa" at the end.
-      --show-source         Show the source generate each error or warning.
-      --statistics          Count errors and warnings.
-      --enable-extensions=ENABLE_EXTENSIONS
-                            Enable plugins and extensions that are otherwise
-                            disabled by default
-      --exit-zero           Exit with status code "0" even if there are errors.
-      -j JOBS, --jobs=JOBS  Number of subprocesses to use to run checks in
-                            parallel. This is ignored on Windows. The default,
-                            "auto", will auto-detect the number of processors
-                            available to use. (Default: auto)
-      --output-file=OUTPUT_FILE
-                            Redirect report to a file.
-      --append-config=APPEND_CONFIG
-                            Provide extra config files to parse in addition to the
-                            files found by Flake8 by default. These files are the
-                            last ones read and so they take the highest precedence
-                            when multiple files provide the same option.
-      --config=CONFIG       Path to the config file that will be the authoritative
-                            config source. This will cause Flake8 to ignore all
-                            other configuration files.
-      --isolated            Ignore all found configuration files.
-      --builtins=BUILTINS   define more built-ins, comma separated
-      --doctests            check syntax of the doctests
-      --include-in-doctest=INCLUDE_IN_DOCTEST
-                            Run doctests only on these files
-      --exclude-from-doctest=EXCLUDE_FROM_DOCTEST
-                            Skip these files when running doctests
 
 .. option:: --version
 
-    When specified on the command-line, this will show :program:`Flake8`\ 's
+    Show :program:`Flake8`\ 's version as well as the versions of all plugins
-    version as well as the versions of all plugins installed.
+    installed.
 
-    **This cannot be specified in the config files.**
+    Command-line usage:
+
+    .. prompt:: bash
+
+        flake8 --version
+
+    This **can not** be specified in the config files.
 
 
 .. option:: -h, --help
 
-    When specified on the command-line, this will show a description of how
+    Show a description of how to use :program:`Flake8` and its options.
-    to use :program:`Flake8` and it soptions.
+
+    Command-line usage:
+
+    .. prompt:: bash
+
+        flake8 --help
+        flake8 -h
+
+    This **can not** be specified in the config files.
 
-    **This cannot be specified in the config files.**
 
 .. option::  -v, --verbose
 
-    When specified on the command-line or in configuration, this will
+    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.
 
-    **This can be specified in the config file.**
+    Command-line example:
 
-    Example config file specification:
+    .. prompt:: bash
+
+        flake8 -vv
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
 
     .. code-block:: ini
 
         verbose = 2
+
+
+.. option:: -q, --quiet
+
+    Decrease the verbosity of Flake8's output. Each time you specify it,
+    it will print less and less information.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 -q
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        quiet = 1
+
+
+.. option:: --count
+
+    Print the total number of errors.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --count dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        count = True
+
+
+.. option:: --diff
+
+    Use the unified diff provided on standard in to only check the modified
+    files and report errors included in the diff.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        git diff -u | flake8 --diff
+
+    This **can not** be specified in the config file.
+
+
+.. option:: --exclude=<patterns>
+
+    Provide a comma-separated list of glob patterns to exclude from checks.
+
+    This defaults to: ``.svn,CVS,.bzr,.hg,.git,__pycache__,.tox``
+
+    Example patterns:
+
+    - ``*.pyc`` will match any file that ends with ``.pyc``
+
+    - ``__pycache__`` will match any path that has ``__pycache__`` in it
+
+    - ``lib/python`` will look expand that using :func:`os.path.abspath` and
+      look for matching paths
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --exclude=*.pyc dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        exclude =
+            .tox,
+            __pycache__
+
+
+.. option:: --filename=<patterns>
+
+    Provide a comma-separate list of glob patterns to include for checks.
+
+    This defaults to: ``*.py``
+
+    Example patterns:
+
+    - ``*.py`` will match any file that ends with ``.py``
+
+    - ``__pycache__`` will match any path that has ``__pycache__`` in it
+
+    - ``lib/python`` will look expand that using :func:`os.path.abspath` and
+      look for matching paths
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --filename=*.py dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        filename =
+            example.py,
+            another-example*.py
+
+
+.. option:: --format=<format>
+
+    Select the formatter used to display errors to the user.
+
+    This defaults to: ``default``
+
+    By default, there are two formatters available:
+
+    - default
+
+    - pylint
+
+    Other formatters can be installed. Refer to their documentation for the
+    name to use to select them.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --format=pylint dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        format=pylint
+
+
+.. option:: --hang-closing
+
+    Toggle whether pycodestyle should enforce matching the indentation of the
+    opening bracket's line. When you specify this, it will prefer that you
+    hang the closing bracket rather than match the indentation.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --hang-closing dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        hang_closing = True
+        hang-closing = True
+
+
+.. option:: --ignore=<errors>
+
+    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
+    :option:`--select` for more information.
+
+    For example, if you wish to only ignore ``W234``, then you can specify
+    that. But if you want to ignore all codes that start with ``W23`` you
+    need only specify ``W23`` to ignore them. This also works for ``W2`` and
+    ``W`` (for example).
+
+    This defaults to: ``E121,E123,E126,E226,E24,E704``
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --ignore=E121,E123 dir/
+        flake8 --ignore=E24,E704 dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        ignore =
+            E121,
+            E123
+        ignore = E121,E123
+
+
+.. option:: --max-line-length=<n>
+
+    Set the maximum length that any line (with some exceptions) may be.
+
+    Exceptions include lines that are either strings or comments which are
+    entirely URLs. For example:
+
+    .. code-block:: python
+
+        # https://some-super-long-domain-name.com/with/some/very/long/path
+
+        url = (
+            'http://...'
+        )
+
+    This defaults to: 79
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --max-line-length 99 dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        max-line-length = 79
+
+
+.. option:: --select=<errors>
+
+    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``.
+
+    This has no default value.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --select=E431,E5,W,F dir/
+        flake8 --select=E,W dir/
+
+    This can also be combined with :option:`--ignore`:
+
+    .. prompt:: bash
+
+        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
+    to be.
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        select =
+            E431,
+            W,
+            F
+
+
+.. option:: --disable-noqa
+
+    Report all errors, even if it is on the same line as a ``# NOQA`` comment.
+    ``# NOQA`` can be used to silence messages on specific lines. Sometimes,
+    users will want to see what errors are being silenced without editing the
+    file. This option allows you to see all the warnings, errors, etc.
+    reported.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --disable-noqa dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        disable_noqa = True
+        disable-noqa = True
+
+
+.. option:: --show-source
+
+    Print the source code generating the error/warning in question.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --show-source dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        show_source = True
+        show-source = True
+
+
+.. option:: --statistics
+
+    Count the number of occurrences of each error/warning code and
+    print a report.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --statistics
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        statistics = True
+
+
+.. option:: --enable-extensions=<errors>
+
+    Enable off-by-default extensions.
+
+    Plugins to Flake8 have the option of registering themselves as
+    off-by-default. These plugins effectively add themselves to the
+    default ignore list.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --enable-extensions=H111 dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        enable-extensions =
+            H111,
+            G123
+        enable_extensions =
+            H111,
+            G123
+
+
+.. option:: --exit-zero
+
+    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.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --exit-zero dir/
+
+    This **can not** be specified in the config file.
+
+
+.. option:: --jobs=<n>
+
+    Specify the number of subprocesses that Flake8 will use to run checks in
+    parallel.
+
+    .. note::
+
+        This option is ignored on Windows because :mod:`multiprocessing` does
+        not support Windows across all supported versions of Python.
+
+    This defaults to: ``auto``
+
+    The default behaviour will use the number of CPUs on your machine as
+    reported by :func:`multiprocessing.cpu_count`.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --jobs=8 dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        jobs = 8
+
+
+.. option:: --output-file=<path>
+
+    Redirect all output to the specified file.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --output-file=output.txt dir/
+        flake8 -vv --output-file=output.txt dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        output-file = output.txt
+        output_file = output.txt
+
+
+.. 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
+    into the Configuration Parser, so it has the highest precedence if it
+    provides an option specified in another config file.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --append-config=my-extra-config.ini dir/
+
+    This **can not** be specified in the config file.
+
+
+.. 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.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --config=my-only-config.ini dir/
+
+    This **can not** be specified in the config file.
+
+
+.. option:: --isolated
+
+    Ignore any config files and use Flake8 as if there were no config files
+    found.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --isolated dir/
+
+    This **can not** be specified in the config file.
+
+
+.. option:: --builtins=<builtins>
+
+    Provide a custom list of builtin functions, objects, names, etc.
+
+    This allows you to let pyflakes know about builtins that it may
+    not immediately recognize so it does not report warnings for using
+    an undefined name.
+
+    This is registered by the default PyFlakes plugin.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --builtins=_,_LE,_LW dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        builtins =
+            _,
+            _LE,
+            _LW
+
+
+.. option:: --doctests
+
+    Enable PyFlakes syntax checking of doctests in docstrings.
+
+    This is registered by the default PyFlakes plugin.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --doctests dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        doctests = True
+
+
+.. option:: --include-in-doctest=<paths>
+
+    Specify which files are checked by PyFlakes for doctest syntax.
+
+    This is registered by the default PyFlakes plugin.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --include-in-doctest=dir/subdir/file.py,dir/other/file.py dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        include-in-doctest =
+            dir/subdir/file.py,
+            dir/other/file.py
+        include_in_doctest =
+            dir/subdir/file.py,
+            dir/other/file.py
+
+
+.. option:: --exclude-from-doctest=<paths>
+
+    Specify which files are not to be checked by PyFlakes for doctest syntax.
+
+    This is registered by the default PyFlakes plugin.
+
+    Command-line example:
+
+    .. prompt:: bash
+
+        flake8 --exclude-in-doctest=dir/subdir/file.py,dir/other/file.py dir/
+
+    This **can** be specified in the config file.
+
+    Example config file usage:
+
+    .. code-block:: ini
+
+        exclude-in-doctest =
+            dir/subdir/file.py,
+            dir/other/file.py
+        exclude_in_doctest =
+            dir/subdir/file.py,
+            dir/other/file.py