Cleaning up documentation surrounding the pre-commit hook [#484]

.pre-commit-config.yaml

@@ -39,7 +39,7 @@ repos:
         args:
         -    --max-line-length=120
 -   repo: https://github.com/pre-commit/mirrors-isort
-    rev: v5.9.3
+    rev: v5.10.1
     hooks:
     -   id: isort
         args: ["--profile", "black", "--filter-files"]

README.rst

@@ -148,10 +148,37 @@ text to your repositories' ``.pre-commit-config.yaml``::
 
     repos:
     -   repo: https://github.com/PyCQA/prospector
-        rev: 1.7.2 # The version of Prospector to use, if not 'master' for latest
+        rev: 1.7.3 # The version of Prospector to use, if not 'master' for latest
         hooks:
         -   id: prospector
 
+This only installs base prospector - if you also use optional tools, for example bandit or mypy, then you can add
+them to the hook configuration like so:
+
+    repos:
+    -   repo: https://github.com/PyCQA/prospector
+        rev: 1.7.3
+        hooks:
+        -   id: prospector
+            additional_requirements:
+            -   bandit
+            -   mypy
+
+For prospector options which affect display only - those which are not configurable using a profile - these can be
+added as command line arguments to the hook. For example:
+
+    repos:
+    -   repo: https://github.com/PyCQA/prospector
+        rev: 1.7.3
+        hooks:
+        -   id: prospector
+            additional_requirements:
+            -   bandit
+            -   mypy
+            args:
+            -   --summary-only
+            -   --zero-exit
+
 License
 -------
 

docs/_templates/globaltoc.html

@@ -6,7 +6,8 @@ <h3><a href="{{ pathto(master_doc) }}">{{ _('Table Of Contents') }}</a></h3>
   <li><a href="{{ pathto('profiles') }}">3. Profiles / Configuration</a></li>
   <li><a href="{{ pathto('suppression') }}">4. Error Suppression</a></li>
   <li><a href="{{ pathto('supported_tools') }}">5. Supported tools</a></li>
-  <li><a href="{{ pathto('contrib') }}">6. Contributing</a></li>
+  <li><a href="{{ pathto('pre-commit') }}">6. Pre-commit Hook</a></li>
+  <li><a href="{{ pathto('contrib') }}">7. Contributing</a></li>
   <li><a href="{{ pathto('changelog') }}">Changelog</a></li>
   <li><a href="{{ pathto('contents') }}">Contents</a></li>
 </ul>

docs/_templates/sidebarintro.html

@@ -1,4 +1,4 @@
 <h3>About prospector</h3>
 <p>
-  Prospector runs your favourite linters in a useful way
+  Prospector runs your favourite linters
 </p>

docs/contents.rst

@@ -11,6 +11,7 @@ Contents
    profiles
    suppression
    supported_tools
+   pre-commit
    contrib
 
 

docs/index.rst

@@ -91,6 +91,8 @@ This will output a list of messages pointing out potential problems or errors, f
 
 Read about the full list of options in the :doc:`usage <usage>` page.
 
+It is also possible to use prospector as a :doc:`pre-commit hook <pre-commit>`.
+
 
 Behaviour
 ---------
@@ -144,6 +146,12 @@ There is more detail about profiles and how to use them on
 :doc:`the profiles documentation <profiles>` page.
 
 
+Pre-commit Hook
+```````````````
+
+Prospector can be configured as a `pre-commit <https://pre-commit.com>`_ hook.
+
+For more information see :doc:`the pre-commit documentation <pre-commit>`.
 
 
 License

docs/pre-commit.rst

@@ -0,0 +1,52 @@
+Pre-commit Hook
+===============
+
+If you'd like Prospector to be run automatically when making changes to files in your Git
+repository, you can install `pre-commit`_ and add the following
+text to your repositories' ``.pre-commit-config.yaml``::
+
+    repos:
+    -   repo: https://github.com/PyCQA/prospector
+        rev: 1.7.3 # The version of Prospector to use, if not 'master' for latest
+        hooks:
+        -   id: prospector
+
+.. _pre-commit: https://pre-commit.com/
+
+Commandline Arguments
+---------------------
+
+Some controls for prospector, especially surrounding how the output is displayed, are not
+:doc:`configurable from a profile <profiles>`, only from the commandline.
+
+To add command-line arguments to the pre-commit hook config file::
+
+    repos:
+    -   repo: https://github.com/PyCQA/prospector
+        rev: 1.7.3
+        hooks:
+        -   id: prospector
+            args:
+            -   --summary-only
+
+
+Optional Tools
+--------------
+
+By default the configuration will only install :doc:`the base supported tools <supported_tools>` and not optional tools.
+
+If you also use optional tools, for example bandit or mypy, then you can add
+them to the hook configuration like so::
+
+    repos:
+    -   repo: https://github.com/PyCQA/prospector
+        rev: 1.7.3
+        hooks:
+        -   id: prospector
+            additional_requirements:
+            -   bandit
+            -   mypy
+
+This is equivalent to running::
+
+    pip install prospector[with_bandit,with_mypy]

docs/reference.rst

@@ -36,12 +36,12 @@ Tool classes
     :members:
 
 :class:`PycodestyleTool`
--------------------
+------------------------
 .. autoclass:: prospector.tools.pycodestyle.PycodestyleTool
     :members:
 
 :class:`PydocstyleTool`
--------------------
+-----------------------
 .. autoclass:: prospector.tools.pydocstyle.PydocstyleTool
     :members:
 

docs/supported_tools.rst

@@ -33,7 +33,7 @@ and is the source of most messages that prospector outputs.
 
 
 `pycodestyle <https://pycodestyle.pycqa.org/en/latest/>`_
-```````````````````````````````````````````````````
+`````````````````````````````````````````````````````````
 
 pycodestyle is a simple tool to warn about violations of the
 `PEP8 style guide <https://www.python.org/dev/peps/pep-0008/>`_. It produces
@@ -79,7 +79,7 @@ not be in a public project, such as secret keys, passwords, AWS tokens or
 source control diffs.
 
 `Pydocstyle <https://github.com/PyCQA/pydocstyle>`_
-````````````````````````````````````````````````````````````
+```````````````````````````````````````````````````
 
 Pydocstyle is a simple tool to warn about violations of the
 `PEP257 Docstring Conventions <http://legacy.python.org/dev/peps/pep-0257/>`_.
@@ -113,7 +113,7 @@ They are also not installed by default. The instructions for installing each too
 section below. For more detailed information on installing, see :doc:`install section<index>`.
 
 `Pyroma <https://github.com/regebro/pyroma>`_
-````````````````````````````````````````````````
+`````````````````````````````````````````````
 Pyroma is a tool to check your `setup.py` to ensure it is following best practices
 of the Python packaging ecosystem. It will warn you if you are missing any package
 metadata which would improve the quality of your package. This is recommended if you
@@ -126,7 +126,7 @@ To install and use::
 
 
 `Vulture <https://github.com/jendrikseipp/vulture>`_
-```````````````````````````````````````````````````````
+````````````````````````````````````````````````````
 
 Vulture finds unused classes, functions and variables in your code. This could
 be useful if your project is an application rather than a library, however, if
@@ -153,7 +153,7 @@ To install and use::
 
 
 `Mypy <https://github.com/python/mypy>`_
-``````````````````````````````````````````````````````
+````````````````````````````````````````
 Mypy is an experimental optional static type checker for Python that aims to combine
 the benefits of dynamic (or "duck") typing and static typing. Mypy combines the
 expressive power and convenience of Python with a powerful type system and
@@ -167,7 +167,7 @@ To install and use::
 
 
 `Bandit <https://github.com/PyCQA/bandit>`_
-``````````````````````````````````````````````````````
+```````````````````````````````````````````
 Bandit finds common security issues in Python code.
 
 To install and use::