Updates the documentation to include installation of the pre-commit hooks

docs/contributing.rst

@@ -19,114 +19,28 @@ How to Get Your Changes Rolled Into Paperless
 If you've found a bug, but don't know how to fix it, you can always post an
 issue on `GitHub`_ in the hopes that someone will have the time to fix it for
 you.  If however you're the one with the time, pull requests are always
-welcome, you just have to make sure that your code conforms to a few standards:
+welcome, you just have to make sure that your code conforms to a few standards.
 
-Pep8
+pre-commit Hooks
-----
-
-It's the standard for all Python development, so it's `very well documented`_.
-The short version is:
-
-* Lines should wrap at 79 characters
-* Use ``snake_case`` for variables, ``CamelCase`` for classes, and ``ALL_CAPS``
-  for constants.
-* Space out your operators: ``stuff + 7`` instead of ``stuff+7``
-* Two empty lines between classes, and functions, but 1 empty line between
-  class methods.
-
-There's more to it than that, but if you follow those, you'll probably be
-alright.  When you submit your pull request, there's a pep8 checker that'll
-look at your code to see if anything is off.  If it finds anything, it'll
-complain at you until you fix it.
-
-
-Additional Style Guides
 -----------------------
 
-Where pep8 is ambiguous, I've tried to be a little more specific.  These rules
+To ensure a consistent style and formatting across the project source, the project
-aren't hard-and-fast, but if you can conform to them, I'll appreciate it and
+utilizes a Git `pre-commit` hook to preform some formatting and linting before a
-spend less time trying to conform your PR before merging:
+commit is allowed.  That way, everyone uses the same style and some common issues
+can be caught early on.
 
+The first time you are setting up to contribute, you'll need to install this hook.
+If you've followed the initial development setup instructions, just run the following:
 
-Function calls
+.. code:: shell-session
-..............
 
-If you're calling a function and that necessitates more than one line of code,
+        pre-commit install
-please format it like this:
 
-.. code:: python
+That's it!  The hooks will now run when you commit. If the formatting isn't quite right
-
+or a linter catches something, the commit will be rejected.  You'll need to look at the
-    my_function(
+output and fix the issue.  Some hooks, such as the Python formatting tool `black`
-        argument1,
+will format failing files, so all you need to do is `git add` those files again and retry your
-        kwarg1="x",
+commit.
-        kwarg2="y"
-        another_really_long_kwarg="some big value"
-        a_kwarg_calling_another_long_function=another_function(
-            another_arg,
-            another_kwarg="kwarg!"
-        )
-    )
-
-This is all in the interest of code uniformity rather than anything else.  If
-we stick to a style, everything is understandable in the same way.
-
-
-Quoting Strings
-...............
-
-pep8 is a little too open-minded on this for my liking.  Python strings should
-be quoted with double quotes (``"``) except in cases where the resulting string
-would require too much escaping of a double quote, in which case, a single
-quoted, or triple-quoted string will do:
-
-.. code:: python
-
-    my_string = "This is my string"
-    problematic_string = 'This is a "string" with "quotes" in it'
-
-In HTML templates, please use double-quotes for tag attributes, and single
-quotes for arguments passed to Django template tags:
-
-.. code:: html
-
-    <div class="stuff">
-        <a href="{% url 'some-url-name' pk='w00t' %}">link this</a>
-    </div>
-
-This is to keep linters happy they look at an HTML file and see an attribute
-closing the ``"`` before it should have been.
-
---
-
-That's all there is in terms of guidelines, so I hope it's not too daunting.
-
-
-Indentation & Spacing
-.....................
-
-When it comes to indentation:
-
-* For Python, the rule is: follow pep8 and use 4 spaces.
-* For Javascript, CSS, and HTML, please use 1 tab.
-
-Additionally, Django templates making use of block elements like ``{% if %}``,
-``{% for %}``, and ``{% block %}`` etc. should be indented:
-
-Good:
-
-.. code:: html
-
-    {% block stuff %}
-    	<h1>This is the stuff</h1>
-    {% endblock %}
-
-Bad:
-
-.. code:: html
-
-    {% block stuff %}
-    <h1>This is the stuff</h1>
-    {% endblock %}
 
 
 The Code of Conduct
@@ -141,5 +55,4 @@ I'm proud to say that the CoC has never had to be enforced because everyone has
 been awesome, friendly, and professional.
 
 .. _GitHub: https://github.com/the-paperless-project/paperless/issues
-.. _very well documented: https://www.python.org/dev/peps/pep-0008/
 .. _code of conduct: https://github.com/the-paperless-project/paperless/blob/master/CODE_OF_CONDUCT.md

docs/extending.rst

@@ -60,27 +60,32 @@ To do the setup you need to perform the steps from the following chapters in a c
 
   * Make sure you're using python 3.9.x or lower. Otherwise you might get issues with building dependencies. You can use `pyenv <https://github.com/pyenv/pyenv>`_ to install a specific python version.
 
-7.  Generate the static UI so you can perform a login to get session that is required for frontend development (this needs to be done one time only). From src-ui directory:
+7.  Install the Git hooks
+    .. code:: shell-session
+
+        pre-commit install
+
+8.  Generate the static UI so you can perform a login to get session that is required for frontend development (this needs to be done one time only). From src-ui directory:
 
     .. code:: shell-session
 
         npm install .
         ./node_modules/.bin/ng build --configuration production
 
-8.  Apply migrations and create a superuser for your dev instance:
+9.  Apply migrations and create a superuser for your dev instance:
 
     .. code:: shell-session
 
         python3 manage.py migrate
         python3 manage.py createsuperuser
 
-9.  Now spin up the dev backend. Depending on which part of paperless you're developing for, you need to have some or all of them running.
+10.  Now spin up the dev backend. Depending on which part of paperless you're developing for, you need to have some or all of them running.
 
     .. code:: shell-session
 
         python3 manage.py runserver & python3 manage.py document_consumer & python3 manage.py qcluster
 
-10. Login with the superuser credentials provided in step 8 at ``http://localhost:8000`` to create a session that enables you to use the backend.
+11. Login with the superuser credentials provided in step 8 at ``http://localhost:8000`` to create a session that enables you to use the backend.
 
 Backend development environment is now ready, to start Frontend development go to ``/src-ui`` and run ``ng serve``. From there you can use ``http://localhost:4200`` for a preview.
 
@@ -108,8 +113,9 @@ Testing and code style:
 *   Run ``pytest`` in the src/ directory to execute all tests. This also generates a HTML coverage
     report. When runnings test, paperless.conf is loaded as well. However: the tests rely on the default
     configuration. This is not ideal. But for now, make sure no settings except for DEBUG are overridden when testing.
-*   Run ``black`` to format your code.
+*   Coding style is enforced by the Git pre-commit hooks.  These will ensure your code is formatted and do some
-*   Run ``pycodestyle`` to test your code for issues with the configured code style settings.
+    linting when you do a `git commit`.
+  * You can also run ``black`` manually to format your code
 
     .. note::