Begin adding user-facing documentation

Especially around invocation and configuration

docs/source/conf.py

@@ -35,6 +35,7 @@ extensions = [
     'sphinx.ext.todo',
     'sphinx.ext.coverage',
     'sphinx.ext.viewcode',
+    'sphinx-prompt',
 ]
 
 # Add any paths that contain templates here, relative to this directory.

docs/source/index.rst

@@ -3,11 +3,14 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Flake8: Your Tool For Style Guide Enforcement
-=============================================
+===============================================
+ Flake8: Your Tool For Style Guide Enforcement
+===============================================
+
+.. _installation-guide:
 
 Installation
-------------
+============
 
 To install Flake8, open an interactive shell and run:
 
@@ -31,7 +34,7 @@ can instead use:
     the version of Python on which it runs.
 
 Quickstart
-----------
+==========
 
 To start using Flake8, open an interactive shell and run:
 
@@ -64,7 +67,7 @@ Please read our user guide for more information about how to use and configure
 Flake8.
 
 User Guide
-----------
+==========
 
 .. toctree::
     :maxdepth: 2
@@ -72,7 +75,7 @@ User Guide
     user/index
 
 Plugin Developer Guide
-----------------------
+======================
 
 .. toctree::
     :maxdepth: 2
@@ -80,7 +83,7 @@ Plugin Developer Guide
     dev/index
 
 Developer Guide
----------------
+===============
 
 .. toctree::
     :maxdepth: 2

docs/source/user/configuration.rst

@@ -0,0 +1,29 @@
+====================
+ Configuring Flake8
+====================
+
+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.
+
+This section will show you how to make
+
+.. prompt:: bash
+
+    flake8
+
+Remember that you want to specify certain options without writing
+
+.. prompt:: bash
+
+    flake8 --select E123,W456 --enable-extensions H111
+
+
+Configuration Locations
+=======================
+
+Presently, Flake8 supports storing its configuration in the following places:
+
+- Your top-level user directory
+
+- In your project in one of ``setup.cfg``, ``tox.ini``, or ``.flake8``.

docs/source/user/index.rst

@@ -12,6 +12,17 @@ Flake8 can be used in many ways:
 
 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
+    the :ref:`installation-guide` section for how to install Flake8.
+
+.. toctree::
+    :maxdepth: 2
+
+    invocation
+    configuration
+
 .. config files
 .. command-line tutorial
 .. VCS usage

docs/source/user/invocation.rst

@@ -0,0 +1,144 @@
+.. _invocation:
+
+=================
+ Invoking Flake8
+=================
+
+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
+like so:
+
+.. prompt:: bash
+
+    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
+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:
+
+.. prompt:: bash
+
+    python2.7 -m flake8
+
+Or
+
+.. prompt:: bash
+
+    python3.5 -m 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
+    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:
+
+.. prompt:: bash
+
+    flake8 --select E123
+
+Or
+
+.. prompt:: bash
+
+    python<version> -m flake8 --select E123
+
+.. note::
+
+    This is the last time we will show both versions of an invocation.
+    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
+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
+we only want errors from files found inside ``my_project`` we can do:
+
+.. prompt:: bash
+
+    flake8 my_project
+
+And if we only want certain errors (e.g., ``E123``) from files in that
+directory we can also do:
+
+.. prompt:: bash
+
+    flake8 --select E123 my_project
+
+If you want to explore more options that can be passed on the command-line,
+you can use the ``--help`` option:
+
+.. prompt:: bash
+
+    flake8 --help
+
+And you should see something like:
+
+.. code::
+
+    Usage: flake8 [options] file file ...
+
+    Options:
+      --version             show program's version number and exit
+      -h, --help            show this help message and exit
+      -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.
+      --enabled-extensions=ENABLED_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
+
+    Installed plugins: pyflakes: 1.0.0, pep8: 1.7.0

tox.ini

@@ -89,6 +89,7 @@ commands =
 deps =
     sphinx>=1.3.0
     sphinx_rtd_theme
+    sphinx-prompt
 commands =
     sphinx-build -E -W -c docs/source/ -b html docs/source/ docs/build/html