diff --git a/docs/source/user/index.rst b/docs/source/user/index.rst index 255ec27..0df911e 100644 --- a/docs/source/user/index.rst +++ b/docs/source/user/index.rst @@ -24,6 +24,7 @@ This guide will cover all of these and the nuances for using |Flake8|. configuration options ignoring-errors + using-plugins python-api .. config files diff --git a/docs/source/user/using-plugins.rst b/docs/source/user/using-plugins.rst new file mode 100644 index 0000000..fad1911 --- /dev/null +++ b/docs/source/user/using-plugins.rst @@ -0,0 +1,66 @@ +================================== + Using Plugins For Fun and Profit +================================== + +|Flake8| is useful on its own but a lot of |Flake8|'s popularity is due to +its extensibility. Our community has developed :term:`plugin`\ s that augment +|Flake8|'s behaviour. Most of these plugins are uploaded to PyPI_. The +developers of these plugins often have some style they wish to enforce. + +For example, `flake8-docstrings`_ adds a check for :pep:`257` style +conformance. Others attempt to enforce consistency, like `flake8-future`_. + +.. note:: + + The accuracy or reliability of these plugins may vary wildly from plugin + to plugin and not all plugins are guaranteed to work with |Flake8| 3.0. + +To install a third-party plugin, make sure that you know which version of +Python (or pip) you used to install |Flake8|. You can then use the most +appropriate of: + +.. prompt:: bash + + pip install + pip3 install + python -m pip install + python2.7 -m pip install + python3 -m pip install + python3.4 -m pip install + python3.5 -m pip install + +To install the plugin, where ```` is the package name on PyPI_. +To verify installation use: + +.. prompt:: bash + + flake8 --version + python -m flake8 --version + +To see the plugin's name and version in the output. + +.. seealso:: :ref:`How to Invoke Flake8 ` + +After installation, most plugins immediately start reporting :term:`error`\ s. +Check the plugin's documentation for which error codes it returns and if it +disables any by default. + +.. note:: + + You can use both :option:`flake8 --select` and :option:`flake8 --ignore` + with plugins. + +Some plugins register new options, so be sure to check :option:`flake8 --help` +for new flags and documentation. These plugins may also allow these flags to +be specified in your configuration file. Hopefully, the plugin authors have +documented this for you. + +.. seealso:: :ref:`Configuring Flake8 ` + + +.. _PyPI: + https://pypi.io/ +.. _flake8-docstrings: + https://pypi.io/project/flake8-docstrings/ +.. _flake8-future: + https://pypi.io/project/flake8-future/