Added documentation about installing pre-commit, as well as the default hooks. (#163)

Author: drewoldag

docs/practices/precommit.rst

@@ -10,9 +10,51 @@ Using pre-commit enables a quick check of your code before it's committed and ch
 by GitHub workflows. This cuts down on code feedback time, and allows for faster 
 development. Additional documentation can be found `here <https://pre-commit.com/index.html>`_.
 
-To configure pre-commit for your project, run the following command register 
+To configure pre-commit for your project, run the following command to register 
 pre-commit hooks with ``.git/hooks/pre-commit``.
 
 .. code-block:: bash
     
     pre-commit install
+
+List of ``pre-commit`` hooks
+-----------------------------
+
+The following is a list of pre-commit hooks that will be run each time you 
+commit code locally. The configuration file that defines these hooks is called 
+``.pre-commit-config.yaml``, you should feel free to update or remove any 
+of these that are not useful for your project. 
+
+.. list-table:: Pre-commit hooks
+   :widths: auto
+   :header-rows: 1
+
+   * - **Hook name**
+     - **Purpose**
+   * - Check template version
+     - Compare the current local template version against latest remote version and alert user if an update is recommended.
+   * - Clear output from Jupyter notebooks
+     - Clear output from Jupyter notebooks to avoid committing large binary files.
+   * - Run unit tests
+     - Run all unit tests that are discovered by pytest.
+   * - Prevent main branch commits
+     - Prevents accidental commits directly to the ``main`` (or ``master``) branches.
+   * - Check for large files
+     - Prevents committing very large files. The default file size threshold is 500kb and is configurable.
+   * - Validate pyproject.toml
+     - Verify pyproject.toml adheres to the required schema to avoid changes that would break the build.
+   * - isort (python files in src/ and tests/)
+     - Runs isort to sort and organize your python package imports. *(Optionally installed when project is created.)*
+   * - pylint (python files in src/)
+     - Runs pylint to enforce a particular code style on python files in the src/ directory. *(Optionally installed when project is created.)*
+   * - pylint (python files in tests/)
+     - Same as above, but for the tests/ directory. *(Optionally installed when project is created.)*
+   * - black
+     - Runs black to enforce a particular code style on python files in the src/ and tests/ directories. *(Optionally installed when project is created.)*
+   * - mypy
+     - Runs static type checking on python files in the src/ and tests/ directories. *(Optionally installed when project is created.)*
+   * - Build documentation with Sphinx
+     - Ensures that automatically generated documentation and, optionally, jupyter notebooks can be built successfully.
+
+
+Many other pre-commit hooks exist, a partial list can be found `here <https://pre-commit.com/hooks.html>`_.

docs/source/existing_project.rst

@@ -193,8 +193,15 @@ Use pre-commit
 ..............
 
 Install and use ``pre-commit``. It may seem annoying at first, but it will save 
-you many cycles of "see a test fail on GitHub, make and push a change, hope the test passes".
+you many cycles of "see a test fail on GitHub, make and push a change, hope the 
+test passes". Installation is easy!
 
+.. code:: bash
+
+    >> pre-commit install
+
+For more information about ``pre-commit`` including a list of the checks that 
+will be run before each commit, check out :doc:`pre-commit <../practices/precommit>`.
 
 Import sorting
 ..............

docs/source/new_project.rst

@@ -90,10 +90,6 @@ At this point, your new project is hydrated and ready for you to start coding. B
 Commit your new project locally
 -------------------------------------------------------------------------------
 
-If you're interested in using pre-commit hooks to crosscheck your code before you commit it, 
-now is a good time to set that up (it's just one command) - check out
-:doc:`pre-commit <../practices/precommit>`
-
 Commit the project to your local version control like so to see the pre-commit checks run.
 
 .. code-block:: bash
@@ -114,3 +110,18 @@ Create a new repository in GitHub: (`GitHub How-to <https://docs.github.com/en/g
     >> git push origin <local_branch_name>
 
 Notice that when you create a PR in GitHub, a set of tests for Continuous Integration starts up to verify that the project can build successfully and that all the unit tests pass. Neato!
+
+Install pre-commit
+----------------------------
+
+Now that your project has been pushed to a GitHub remote repository, it's a good 
+time to install ``pre-commit`` so that future commits will run a suite of checks 
+before pushing code to the remote repository. 
+Run the following command in your terminal.
+
+.. code:: bash
+
+    >> pre-commit install
+
+For more information about ``pre-commit`` including a list of the checks that 
+will be run before each commit, please see :doc:`pre-commit <../practices/precommit>`.