Move pre-commit to more general section

Author: ArBridgeman

doc/user_guide/features/formatting_code/index.rst

@@ -40,35 +40,6 @@ deterministic manner.
 |                    |                  | need to be re-formatted            |
 +--------------------+------------------+------------------------------------+
 
-.. _pre_commit:
-
-pre-commit
-++++++++++++
-
-`Pre-commit <https://pre-commit.com/>`__ is a framework that automatically runs
-configurable checks and fixes on code before Git commits and pushes.
-Included in the cookiecutter project template is a ``.pre-commit-config.yaml``, which
-uses the formatting :ref:`formatting_sessions`. For information on configuring and
-setting it up see :ref:`pre-commit_configuration`.
-
-Once it's ready to use, the process is:
-
-#. Make your code changes
-#. ``git add -u`` and ``git commit -m "<message>"``
-#. pre-commit performs checks on the changed files and produces an output like
-
-    .. code-block:: bash
-
-        code-format..........................................(no files to check)Skipped
-        check yaml...........................................(no files to check)Skipped
-        fix end of files.........................................................Passed
-        trim trailing whitespace.................................................Passed
-
-   * If all steps pass, then no action is needed.
-   * If a step fails, then check the output further. If it was an automatic fix, then
-     just add the altered file to your commit and execute your ``git commit`` line again.
-     Otherwise, you will need to take on manual intervention.
-
 .. _formatting_configuration:
 
 Configuration
@@ -98,23 +69,6 @@ Ensure ``isort`` is configured with compatibility for ``black``:
 For further configuration options, see
 `isort options <https://pycqa.github.io/isort/docs/configuration/options.html>`__.
 
-.. _pre-commit_configuration:
-
-pre-commit
-^^^^^^^^^^
-#. Add a :code:`.pre-commit-config.yaml` file to your project root
-
-    Feel free to get some inspiration from the Python toolbox itself:
-
-    .. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/.pre-commit-config.yaml
-       :language: yaml
-
-#. Enable pre-commit hooks for your workspace
-
-    .. code-block:: shell
-
-        poetry run -- pre-commit install --hook-type pre-commit --hook-type pre-push
-
 
 pyupgrade
 ^^^^^^^^^

doc/user_guide/features/formatting_code/troubleshooting.rst

@@ -1,3 +1,5 @@
+.. _formatting_troubleshooting:
+
 Troubleshooting
 ===============
 

doc/user_guide/features/github_hooks/index.rst

@@ -0,0 +1,82 @@
+.. _github_hooks:
+
+Enabling GitHub Hooks
+=====================
+
+.. toctree::
+    :maxdepth: 2
+
+    troubleshooting
+
+GitHub hooks are automated scripts that run at specific points during Git's execution,
+allowing developers to enforce quality standards, automate tasks, and customize Git's
+behavior. The PTB uses the `pre-commit <https://pre-commit.com/>`__ framework to
+define common GitHub hooks for Git commits and pushes. The configuration for
+``pre-commit``  is provided in a ``.pre-commit-config.yaml`` file and described in
+:ref:`pre-commit_configuration`.
+
+.. _pre-commit_configuration:
+
+Configuration
++++++++++++++
+
+#. Add a ``.pre-commit-config.yaml`` file to your project's root directory. Feel free to
+   take inspiration from the example ``.pre-commit-config.yaml``:
+
+    .. collapse:: .pre-commit-config.yaml
+
+        .. literalinclude:: ../../../../project-template/{{cookiecutter.repo_name}}/.pre-commit-config.yaml
+           :language: yaml
+
+
+#. Enable pre-commit hooks for your workspace:
+
+    .. code-block:: shell
+
+        poetry run -- pre-commit install --hook-type pre-commit --hook-type pre-push
+
+
+Working with ``pre-commit``
++++++++++++++++++++++++++++
+
+.. _committing:
+
+Committing
+----------
+
+Once ``pre-commit`` has been configured, the process for performing a ``git commit`` is:
+
+#. Make your code changes
+#. ``git add`` changed files and ``git commit -m "<message>"``
+#. ``pre-commit`` performs checks on the changed files and produces an output like
+
+    .. code-block:: bash
+
+        code-format..........................................(no files to check)Skipped
+        check yaml...........................................(no files to check)Skipped
+        fix end of files.........................................................Passed
+        trim trailing whitespace.................................................Passed
+
+   * If all steps pass, then no action is needed.
+   * If a step fails, then check the output further. If it was an automatic fix, then
+     just add the altered file to your commit and execute your ``git commit`` line again.
+     Otherwise, manual intervention is needed.
+
+Pushing
+-------
+
+Once ``pre-commit`` has been configured, the process for performing a ``git push`` is:
+
+#. Perform one or more iterations of :ref:`committing`.
+#. ``git push``
+#. ``pre-commit`` performs checks on the changed files and produces an output like
+
+    .. code-block:: bash
+
+        type-check...............................................................Passed
+        lint.....................................................................Passed
+
+   * If all steps pass, then no action is needed.
+   * If a step fails, then check the output further. The suggested ``pre-push`` actions
+     given in the :ref:`pre-commit_configuration` require manual intervention. Create
+     a new commit to resolve the issue & try ``git push`` again.

doc/user_guide/features/github_hooks/troubleshooting.rst

@@ -0,0 +1,12 @@
+Troubleshooting
+===============
+
+The checks for ``git commit`` or ``git push`` keep failing
+----------------------------------------------------------
+
+The ``pre-commit`` hooks, as defined in the ``.pre-commit-config.yaml``
+use multiple nox sessions. If a step fails multiple times, despite a user adding fixes
+or manually resolving the error, then please check which nox session is failing
+and refer to its troubleshooting documentation for help:
+
+* :ref:`Formatting Troubleshooting <formatting_troubleshooting>`

doc/user_guide/features/index.rst

@@ -9,6 +9,7 @@ Features
     metrics/collecting_metrics
     creating_a_release
     documentation/index
+    github_hooks/index
     formatting_code/index
     managing_dependencies
 

doc/user_guide/getting_started.rst

@@ -131,8 +131,8 @@ straightforward, and you just can use the example ``noxfile.py`` below.
 
     For additional information on resolving this issue, please :ref:`refer to <faq_no_module_noxconfig>`.
 
-5. Set up the pre-commit hooks [optional]
-+++++++++++++++++++++++++++++++++++++++++
+5. Set up the GitHub ``pre-commit`` hooks [optional]
+++++++++++++++++++++++++++++++++++++++++++++++++++++
 
 See :ref:`pre-commit_configuration` for the required steps.