pre-commit/flake8
1
0
Fork 0
mirror of https://github.com/PyCQA/flake8.git synced 2026-04-06 13:06:53 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

Use |Flake8| consistently throughout documentation

Browse source
This commit is contained in:
Ian Cordasco 2016-06-20 08:13:50 -05:00
parent 57ac6ab699
commit 41277ff965
No known key found for this signature in database
GPG key ID: 656D3395E4A9791A
19 changed files with 192 additions and 167 deletions
Download patch file Download diff file Expand all files Collapse all files

35
docs/source/user/configuration.rst
View file

@ -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
sub-directories. Let's take for example Flake8's own project structure
|Flake8| is written with the understanding that people organize projects into
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
as a format). This means that any Flake8 configuration you wish to set needs
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
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
file. See :ref:`our list of options <options-list>` to determine which
options will be parsed from the configuration files.
Not every |Flake8| command-line option can be specified in the
configuration file. See :ref:`our list of options <options-list>` to
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

8
docs/source/user/ignoring-errors.rst
View file

@ -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`

8
docs/source/user/index.rst
View file

@ -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
the :ref:`installation-guide` section for how to install Flake8.
This portion of |Flake8|'s documentation does not cover installation. See
the :ref:`installation-guide` section for how to install |Flake8|.
.. toctree::
:maxdepth: 2

16
docs/source/user/invocation.rst
View file

@ -4,16 +4,16 @@
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
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
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:
@ -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

31
docs/source/user/options.rst
View file

@ -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

2
docs/source/user/python-api.rst
View file

@ -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.