From 28549173962d14d882866f37a922147c83916261 Mon Sep 17 00:00:00 2001 From: carlio Date: Fri, 3 Oct 2014 09:02:18 +0200 Subject: [PATCH] [refs #24] Further additions to documentation, mostly surrounding profiles --- docs/contrib.rst | 2 + docs/index.rst | 98 ++++++++++++++++++++------------- docs/profiles.rst | 113 +++++++++++++++++++++++++++++++++++++++ docs/supported_tools.rst | 4 ++ 4 files changed, 181 insertions(+), 36 deletions(-) create mode 100644 docs/contrib.rst diff --git a/docs/contrib.rst b/docs/contrib.rst new file mode 100644 index 00000000..04ceaafd --- /dev/null +++ b/docs/contrib.rst @@ -0,0 +1,2 @@ +Development and Contributing +============================ diff --git a/docs/index.rst b/docs/index.rst index 50e054b3..71ca3427 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -17,14 +17,24 @@ Prospector - Python Static Analysis :target: https://coveralls.io/r/landscapeio/prospector :alt: Text Coverage + About ----- Prospector is a tool to analyse Python code and output information about errors, potential problems, convention violations and complexity. -It brings together the functionality of other Python analysis tools such as `Pylint`_, `pep8`_, and `McCabe complexity`_ . See the :doc:`Supported Tools` section for a complete list. +It brings together the functionality of other Python analysis tools such as +`Pylint `_, +`pep8 `_, +and `McCabe complexity `_. +See the :doc:`Supported Tools` section for a complete list. + +The primary aim of Prospector is to be useful 'out of the box'. A common complaint of other +Python analysis tools is that it takes a long time to filter through which errors are relevant +or interesting to your own coding style. Prospector provides some default profiles, which +hopefully will provide a good starting point and will be useful straight away, +and adapts the output depending on the libraries your project uses. -The primary aim of Prospector is to be useful 'out of the box'. A common complaint of other Python analysis tools is that it takes a long time to filter through which errors are relevant or interesting to your own coding style. Prospector provides some default profiles, which hopefully will provide a good starting point and be useful straight away. Installation ------------ @@ -37,7 +47,8 @@ To install optional dependencies such as ``pyroma``:: pip install prospector[with_pyroma] -For a full list of optional extras, see the :doc:`section on supported tools `. +For a full list of optional extras, see the :doc:`page on supported tools `. + Usage ----- @@ -53,40 +64,66 @@ This will output a list of messages pointing out potential problems or errors, f L5:0 ToolBase: pylint - R0922 Abstract class is only referenced 1 times -Read about the full list of options in the :doc:`usage ` section. +Read about the full list of options in the :doc:`usage ` page. -License -------- +Behaviour +--------- + +Adapting to Dependencies +```````````````````````` + +Prospector will `try to detect `_ the +libraries that your project uses, and adapt the output and filtering to those libraries. +For example, if you use Django, the +`pylint-django `_ plugin will be loaded +to help Pylint inspect Django-specific code. + +There is currently support for the following frameworks: + +- `Celery `_ +- `Django `_ + +If you have a suggestion for another framework or library which should be supported, +please `add an issue `_ +or :doc:`consider creating a pull request `. -Prospector is available under the GPLv2 License. +Strictness +`````````` -Appendix --------- +Prospector can be configured to be more or less strict. The more strict, the more errors and +warnings it will find. At higher strictness levels, you may find that the output is a bit too +picky. The default level is designed to give useful output and warnings but also to suppress +messages which are not necessarily useful. -Supported Tools -``````````````` +To change the strictness level:: -Currently, prospector runs the following tools: + prospector --strictness high -- `Pylint`_ -- `Mccabe complexity`_ -- `pyflakes`_ -- `pep8`_ -- `dodgy`_ -- `frosted`_ +Valid levels are ``verylow``, ``low``, ``medium``, ``high`` and ``veryhigh``. -Supported frameworks and libraries -`````````````````````````````````` +Profiles +```````` -Prospector has support for the following frameworks: +A profile is a YAML file containing various directives about which messages and which tools +to allow or disable. Profiles can inherit from each other, allowing you to adapt the behaviour +of existing profiles or compose several smaller specialised profiles into one to suit your +project. -- `Celery`_ -- `Django`_ +Note that the 'strictness' is implemented as a profile. -If you have a suggestion for another framework or library which should be supported, please `add an issue`_. +There is more detail about profiles and how to use them on +:doc:`the profiles documentation ` page. + + + + +License +------- + +Prospector is available under the GPLv2 License. Contents: @@ -99,6 +136,7 @@ Contents: strictness profiles supported_tools + contrib @@ -108,15 +146,3 @@ Indices and tables * :ref:`genindex` * :ref:`modindex` * :ref:`search` - - -.. _detecting dependencies: https://github.com/landscapeio/requirements-detector -.. _Pylint: http://docs.pylint.org/ -.. _McCabe complexity: https://pypi.python.org/pypi/mccabe -.. _pyflakes: https://launchpad.net/pyflakes -.. _pep8: http://pep8.readthedocs.org/en/latest/) (with [pep8-naming](https://github.com/flintwork/pep8-naming) -.. _dodgy: https://github.com/landscapeio/dodgy -.. _frosted: https://github.com/timothycrosley/frosted -.. _Celery: https://github.com/landscapeio/pylint-celery -.. _Django: https://github.com/landscapeio/pylint-django -.. _add an issue: https://github.com/landscapeio/prospector/issues diff --git a/docs/profiles.rst b/docs/profiles.rst index 7028f3dd..868f14b8 100644 --- a/docs/profiles.rst +++ b/docs/profiles.rst @@ -1,2 +1,115 @@ Profiles ======== + +Here is an example profile:: + + inherits: + - no_test_warnings + - strictness_medium + + ignores: + - ^docs/ + + pep8: + disable: + - W602 + - W603 + enable: + - W601 + options: + max-line-length: 79 + + mccabe: + run: false + + +Builtin Profiles +---------------- + +Prospector comes with several built-in profiles, which power some of strictness and style +options. You can see the `full list on GitHub `_. + + +Inheritance +----------- + +Profiles can inherit from other profiles, and can inherit from more than one profile. +Prospector merges together all of the options in each profile, starting at the top +of the inheritance tree and overwriting values with those found lower. + +The example profile above inherits from the 'strictness_medium' profile provided by +prospector. It will take all options from 'strictness_medium' except where new settings +are defined, which will be used in preference. + +For lists, such as the ``ignores`` section, they will be merged together rather than +overwritten - so essentially, the ignores section will accumulate. + +The name of a profile is the filename without the ``.yaml`` extension. So if you create +a profile called 'my_project.yaml', the name will be 'my_project'. Inheritance works +by searching the ``profile-path`` for files matching the name in the inheritance list. + +The ``profile-path`` is where Prospector should search when looking for profiles. By +default, it will look in the directory containing the built-in profiles, as well as +the directory where prospector is runing, and a `.prospector` directory relative to +that. To add additional places to search:: + + prospector --profile-path path/to/your/profiles + + +Ignoring Paths +-------------- + +The ``ignores`` section is a list of regular expressions. The path of each directory and file +that prospector finds is passed to each regular expression and `searched` +(ie, ``re.search`` not ``re.match``). If any matches are found, the file or directory is not +included in the checks. + + +Tool Configuration +------------------ + +Each tool can be individually configured with a section beginning with the tool name +(in lowercase). Valid values are +``pylint``, ``pep8``, ``mccabe``, ``dodgy``, ``pyflakes``, ``frosted``, +``vulture`` and ``pyroma``. + +Enabling and Disabling Tools +```````````````````````````` +There are :doc:`6 default and 2 optional `. Unless otherwise configured, +the defaults are enabled and the optional tools are disabled. + +In a profile, you can enable or disable a tool using the boolean ``run``:: + + pyroma: + run: true + +Note that the ``--tools`` :doc:`command line argument ` overrides profiles if used. + + + +Enabling and Disabling Messages +``````````````````````````````` + +Messages can be enabled or disabled using the tool's code for the output. These codes are +either from the tool itself, or provided by prospector for those tools which do not have +message codes. The list of tools and message codes can be found +`in the tools package`_. + +The typical desired action is to disable messages:: + + pylint: + disable: + - E0202 + - E0203 + +However, you can also enable messages which were disabled by parent profiles: + + pylint: + enable: + - E0202 + - E0203 + + +Tool Options +```````````` + diff --git a/docs/supported_tools.rst b/docs/supported_tools.rst index e38aea91..b8ab2a62 100644 --- a/docs/supported_tools.rst +++ b/docs/supported_tools.rst @@ -50,6 +50,10 @@ some options:: # turn on complete pep8 checking: prospector --full-pep8 + # change the maximum line length allowed + # (the default varies by strictness): + prospector --max-line-length 120 + `pyflakes `_ ````````````````````````````````````````````