[refs #24] Further additions to documentation, mostly surrounding pro…

…files

docs/contrib.rst

@@ -0,0 +1,2 @@
+Development and Contributing
+============================

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<supported_tools>` section for a complete list.
+It brings together the functionality of other Python analysis tools such as 
+`Pylint <http://docs.pylint.org/>`_, 
+`pep8 <http://pep8.readthedocs.org/en/latest/>`_, 
+and `McCabe complexity <https://pypi.python.org/pypi/mccabe>`_. 
+See the :doc:`Supported Tools<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 </supported_tools>`.
+For a full list of optional extras, see the :doc:`page on supported tools <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 <usage>` section.
+Read about the full list of options in the :doc:`usage <usage>` page.
 
 
-License
--------
+Behaviour
+---------
+
+Adapting to Dependencies
+````````````````````````
+
+Prospector will `try to detect <https://github.com/landscapeio/requirements-detector>`_ the
+libraries that your project uses, and adapt the output and filtering to those libraries.
+For example, if you use Django, the 
+`pylint-django <https://github.com/landscapeio/pylint-django>`_ plugin will be loaded 
+to help Pylint inspect Django-specific code.
+
+There is currently support for the following frameworks:
+
+- `Celery <https://github.com/landscapeio/pylint-celery>`_
+- `Django <https://github.com/landscapeio/pylint-django>`_
+
+If you have a suggestion for another framework or library which should be supported, 
+please `add an issue <https://github.com/landscapeio/prospector/issues>`_ 
+or :doc:`consider creating a pull request <contrib>`.
 
-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 <profiles>` 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

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 <https://github.com/landscapeio/prospector/tree/master/prospector/profiles/profiles>`_.
+
+
+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 <supported_tools>`. 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 <usage>` 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<https://github.com/landscapeio/prospector/tree/master/prospector/tools>`_.
+
+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
+````````````
+

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 <https://launchpad.net/pyflakes>`_
 ````````````````````````````````````````````