GH613 Adding documentation to tests.md and workflow file

Author: loicdiridollou

.github/workflows/comment_commands.yml

@@ -7,14 +7,17 @@ permissions:
   checks: write
 
 env:
+  # store mapping of commands to use with poetry
   RUN_COMMAND: '{"/pandas_nightly": "pytest --nightly", "/pyright_strict": "pyright_strict", "/mypy_nightly": "mypy --mypy_nightly"}'
+  # store mapping of labels to display in the check runs
   DISPLAY_COMMAND: '{"/pandas_nightly": "Pandas nightly tests", "/pyright_strict": "Pyright strict tests", "/mypy_nightly": "Mypy nightly tests"}'
 
 jobs:
   optional_tests:
     name: "Optional tests run"
     runs-on: ubuntu-latest
     timeout-minutes: 10
+    # if more commends are added, they will need to be added here too as we don't have avvecc to env at this stage
     if: (github.event.issue.pull_request) && contains(fromJSON('["/pandas_nightly", "/pyright_strict", "/mypy_nightly"]'), github.event.comment.body)
 
     steps:
@@ -27,10 +30,12 @@ jobs:
           python-version: "3.11"
 
       - name: Run ${{ fromJSON(env.DISPLAY_COMMAND)[github.event.comment.body] }}
+        # run the tests based on the value of the comment
         id: tests-step
         run: poetry run poe ${{ fromJSON(env.RUN_COMMAND)[github.event.comment.body] }}
 
       - name: Get head sha and store value
+        # get the sha of the last commit to attach the results of the tests
         if: always()
         id: get-sha
         uses: actions/github-script@v7
@@ -45,6 +50,7 @@ jobs:
             core.setOutput('sha', pr.data.head.sha)
 
       - name: Report results of the tests and publish
+        # publish the results to a check run no matter the pass or fail
         if: always()
         uses: actions/github-script@v7
         with:

docs/tests.md

@@ -5,7 +5,7 @@
 Here are the most important options. Fore more details, please use `poe --help`.
 
 - Run all tests (against both source and installed stubs): `poe test_all`
-- Run tests against the source code: `poe test` 
+- Run tests against the source code: `poe test`
   - Run only mypy: `poe mypy`
   - Run only pyright: `poe pyright`
   - Run only pytest: `poe pytest`
@@ -20,3 +20,9 @@ The following tests are **optional**. Some of them are run by the CI but it is o
 - Use mypy nightly to validate the annotations: `poe mypy --mypy_nightly`
 - Use pyright in full strict mode: `poe pyright_strict`
 - Run stubtest to compare the installed pandas-stubs against pandas (this will fail): `poe stubtest`. If you have created an allowlist to ignore certain errors: `poe stubtest path_to_the_allow_list`
+
+Among the tests above, the following can be run directly during a PR by commenting in the discussion.
+
+- Run pytest against pandas nightly by commenting `\pandas_nightly`
+- Use mypy nightly to validate the annotations by commenting `\mypy_nightly`
+- Use pyright in full strict mode by commenting `\pyright_strict`