docs: Simplify undestanding what's going on (#750)

---------

Co-authored-by: George L. Yermulnik <[email protected]>
Co-authored-by: 🇺🇦 Sviatoslav Sydorenko (Святослав Сидоренко) <[email protected]>

Author: 3 people

.github/CONTRIBUTING.md

@@ -1,11 +1,5 @@
 # Notes for contributors
 
-1. Python hooks are supported now too. All you have to do is:
-    1. add a line to the `console_scripts` array in `entry_points` in `setup.py`
-    2. Put your python script in the `pre_commit_hooks` folder
-
-Enjoy the clean, valid, and documented code!
-
 * [Run and debug hooks locally](#run-and-debug-hooks-locally)
 * [Run hook performance test](#run-hook-performance-test)
   * [Run via BASH](#run-via-bash)
@@ -18,6 +12,7 @@ Enjoy the clean, valid, and documented code!
   * [Prepare basic documentation](#prepare-basic-documentation)
   * [Add code](#add-code)
   * [Finish with the documentation](#finish-with-the-documentation)
+* [Contributing to Python code](#contributing-to-python-code)
 
 ## Run and debug hooks locally
 
@@ -152,5 +147,38 @@ You can use [this PR](https://github.com/antonbabenko/pre-commit-terraform/pull/
 
 ### Finish with the documentation
 
-1. Add hook description to [Available Hooks](../README.md#available-hooks).
+1. Add the hook description to [Available Hooks](../README.md#available-hooks).
 2. Create and populate a new hook section in [Hooks usage notes and examples](../README.md#hooks-usage-notes-and-examples).
+
+## Contributing to Python code
+
+1. [Install `tox`](https://tox.wiki/en/stable/installation.html)
+2. To run tests, run:
+
+    ```bash
+    tox -qq
+    ```
+
+    The easiest way to find out what parts of the code base are left uncovered, is to copy-paste and run the `python3 ...` command that will open the HTML report, so you can inspect it visually.
+
+3. Before committing any changes (if you do not have `pre-commit` installed locally), run:
+
+    ```bash
+    tox r -qq -e pre-commit
+    ```
+
+    Make sure that all checks pass.
+
+4. (Optional): If you want to limit the checks to MyPy only, you can run:
+
+    ```bash
+    tox r -qq -e pre-commit -- mypy --all-files
+    ```
+
+    Then copy-paste and run the `python3 ...` commands to inspect the strictest MyPy coverage reports visually.
+
+5. (Optional): You can find all available `tox` environments by running:
+
+    ```bash
+    tox list
+    ```

.github/workflows/reusable-tox.yml

@@ -297,6 +297,9 @@ jobs:
         --quiet
         --
         python -Im pre_commit install-hooks
+    # Create GHA Job Summary markdown table of the coverage report
+    # But only for 'pytest' env in 'tox'.
+    # For details: ../../tox.ini '[testenv:pytest]' 'commands_post'
     - name: >-
         Run tox envs: `${{ env.TOXENV }}`
       id: tox-run
@@ -313,6 +316,7 @@ jobs:
           && format('-- {0}', inputs.tox-run-posargs)
           || ''
         }}
+    # Generate nice SVG image of passed/failed tests in GHA Job Summary
     - name: Produce markdown test summary from JUnit
       if: >-
         !cancelled()

pytest.ini

@@ -43,7 +43,7 @@ doctest_optionflags = ALLOW_UNICODE ELLIPSIS
 empty_parameter_set_mark = xfail
 
 faulthandler_timeout = 30
-
+# Turn all warnings into errors
 filterwarnings =
   error
 

tox.ini

@@ -14,6 +14,10 @@ warnings-to-errors = -Werror
 description = Run pytest under {envpython}
 dependency_groups =
   testing
+
+# In:
+# 'tox run -e py -- --lf', 'tox run -- --lf', 'tox run -e py313,py312 -- --lf'
+# '{posargs}' (positional arguments) == '--lf'
 commands =
   {envpython} \
     {[python-cli-options]byte-errors} \
@@ -23,6 +27,9 @@ commands =
       {tty:--color=yes} \
       {posargs:--cov-report=html:{envtmpdir}{/}htmlcov{/}}
 commands_post =
+  # Create GHA Job Summary markdown table of the coverage report
+  # https://github.blog/news-insights/product-news/supercharging-github-actions-with-job-summaries/
+  # a leading '-' suppresses non-zero return codes
   -{envpython} \
     {[python-cli-options]byte-errors} \
     {[python-cli-options]max-isolation} \
@@ -38,6 +45,7 @@ commands_post =
       cov = coverage.Coverage(); \
       cov.load(); \
       cov.report(file=gh_summary_fd, output_format="markdown")'
+  # Expose the coverage & test run XML report paths into GHA
   {envpython} \
     {[python-cli-options]byte-errors} \
     {[python-cli-options]max-isolation} \
@@ -165,7 +173,9 @@ commands =
 commands_post =
 package = skip
 
-
+# In:
+# 'tox run -e pre-commit -- mypy-py313 --all'
+# '{posargs}' == 'mypy-py313 --all'
 [testenv:pre-commit]
 description =
   Run the quality checks under {basepython}; run as
@@ -186,6 +196,7 @@ commands =
       {posargs:--all-files}
 
   # Print out the advice on how to install pre-commit from this env into Git:
+  # a leading '-' suppresses non-zero return codes
   -{envpython} \
     {[python-cli-options]byte-errors} \
     {[python-cli-options]max-isolation} \
@@ -219,6 +230,7 @@ commands_post =
       ); \
       print("codecov-flags=MyPy", file=gh_output_fd); \
       gh_output_fd.close()'
+  # Publish available MyPy-produced text and JSON reports wrapped as Markdown code blocks, to a GHA job summary
   {envpython} \
     {[python-cli-options]byte-errors} \
     {[python-cli-options]max-isolation} \