From a7898e038932e771d0499f6dc30b8151d347c472 Mon Sep 17 00:00:00 2001 From: Ian Cordasco Date: Thu, 26 May 2016 13:21:25 -0500 Subject: [PATCH] Begin adding user-facing documentation Especially around invocation and configuration --- docs/source/conf.py | 1 + docs/source/index.rst | 17 ++-- docs/source/user/configuration.rst | 29 ++++++ docs/source/user/index.rst | 11 +++ docs/source/user/invocation.rst | 144 +++++++++++++++++++++++++++++ tox.ini | 1 + 6 files changed, 196 insertions(+), 7 deletions(-) create mode 100644 docs/source/user/configuration.rst create mode 100644 docs/source/user/invocation.rst diff --git a/docs/source/conf.py b/docs/source/conf.py index f30410b..a44bd97 100644 --- a/docs/source/conf.py +++ b/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. diff --git a/docs/source/index.rst b/docs/source/index.rst index d7ed3a2..71b3c94 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/user/configuration.rst b/docs/source/user/configuration.rst new file mode 100644 index 0000000..c3f3e2c --- /dev/null +++ b/docs/source/user/configuration.rst @@ -0,0 +1,29 @@ +==================== + Configuring Flake8 +==================== + +Once you have learned how to :ref:`invoke ` 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``. diff --git a/docs/source/user/index.rst b/docs/source/user/index.rst index 8368509..2085178 100644 --- a/docs/source/user/index.rst +++ b/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 diff --git a/docs/source/user/invocation.rst b/docs/source/user/invocation.rst new file mode 100644 index 0000000..ef763ae --- /dev/null +++ b/docs/source/user/invocation.rst @@ -0,0 +1,144 @@ +.. _invocation: + +================= + Invoking Flake8 +================= + +Once you have :ref:`installed ` 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 -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 -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 diff --git a/tox.ini b/tox.ini index cfbc877..24ef6e8 100644 --- a/tox.ini +++ b/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