turn ci information into tables

story645 · story645 · commit 124edd53eca3 · 2024-01-26T14:56:50.000-05:00
diff --git a/.circleci/config.yml b/.circleci/config.yml
@@ -17,7 +17,7 @@ commands:
             export git_log=$(git log --max-count=1 --pretty=format:"%B" | tr "\n" " ")
             echo "Got commit message:"
             echo "${git_log}"
-            if [[ -v CIRCLE_PULL_REQUEST ]] && ([[ "$git_log" == *"[skip circle]"* ]] || [[ "$git_log" == *"[circle skip]"* ]]); then
+            if [[ -v CIRCLE_PULL_REQUEST ]] && [[ $git_log =~ (\[skip circle\]|\[circle skip\]|\[skip doc\]|\[doc skip\]) ]]; then
               echo "Skip detected, exiting job ${CIRCLE_JOB} for PR ${CIRCLE_PULL_REQUEST}."
               circleci-agent step halt;
             fi
diff --git a/doc/devel/development_workflow.rst b/doc/devel/development_workflow.rst
@@ -464,42 +464,74 @@ Make sure the Linting, GitHub Actions, AppVeyor, CircleCI, and Azure pipelines a
 passing before merging. All checks are listed at the bottom of the GitHub page of your
 pull request.
 
-Here are some tips for finding the cause of a test failure:
-
-- If *Linting* fails, you have a code style issue, which will be listed
-  as annotations on the pull request's diff.
-- If *Mypy* or *Stubtest* fails, you have inconsistency in type hints, which
-  will be listed as annotations in the diff.
-- If a GitHub Actions or AppVeyor run fails, search the log for ``FAILURES``.
-  The subsequent section will contain information on the failed tests.
-- If CircleCI fails, likely you have some reStructuredText style issue in
-  the docs. Search the CircleCI log for ``WARNING``.
-- If Azure pipelines fail with an image comparison error, you can find the
-  images as *artifacts* of the Azure job:
-
-  - Click *Details* on the check on the GitHub PR page.
-  - Click *View more details on Azure Pipelines* to go to Azure.
-  - On the overview page *artifacts* are listed in the section *Related*.
+.. list-table::
+    :header-rows: 1
+    :stub-columns: 1
+    :widths: 20 15 65
+
+    * - name
+      - scope
+      - tips for finding cause of failure
+    * - Linting
+      - Code style
+      - Errors are displayed as annotations on the pull request diff.
+    * - | Mypy
+        | Stubtest
+      - Type hints
+      - Errors are displayed as annotations on the pull request diff.
+    * - CircleCI
+      - reStructuredText (rst)
+      - Search the CircleCI log for ``WARNING``.
+    * - | GitHub Actions
+        | AppVeyor
+        | Azure pipelines
+      - :ref:`tests <testing>`
+      - | Search the log for ``FAILURES``. Subsequent section should contain information
+          on failed tests.
+        |
+        | On Azure, find the images as *artifacts* of the Azure job:
+        | 1. Click *Details* on the check on the GitHub PR page.
+        | 2. Click *View more details on Azure Pipelines* to go to Azure.
+        | 3. On the overview page *artifacts* are listed in the section *Related*.
 
 Skip CI checks
 --------------
 
-If you know only a subset of CIs need to be run, this can be controlled on individual
-commits by including the following substrings in commit messages:
-
-- ``[ci doc]``: restrict the CI to documentation checks. For when you only changed
-  documentation. This skip is automatic if the changes are only under
-  ``doc/`` or ``galleries/``.
-- ``[skip circle]``: skip the documentation build check. For when you didn't
-  change documentation.
-- Unit tests can be turned off for individual platforms with:
-
-  - ``[skip actions]``: GitHub Actions
-  - ``[skip appveyor]``: AppVeyor. Must be in the first line of the commit message.
-  - ``[skip azp]``: Azure Pipelines
-
-- ``[skip ci]``: skip all CIs.  Use this only if you know your changes do not
-  need to be tested at all. This only skips CI triggered on ``on: push`` and
-  ``on: pull_request`` events. For more information, see `Skipping workflow runs`_.
+If you know only a subset of CI checks need to be run, you can skip any unneeded CI
+checks on individual commits by including the following substrings in commit messages:
+
+.. list-table::
+    :header-rows: 1
+    :stub-columns: 1
+    :widths: 25 20 55
+
+    * - substring
+      - effect
+      - notes
+    * - ``[ci doc]``
+      - Only run documentation checks.
+      - | For when you have only changed documentation.
+        | ``[ci doc]`` is applied automatically when the changes are only to files in
+          ``doc/**/`` or ``galleries/**/``
+    * - ``[skip doc]``
+      - Skip documentation checks.
+      - For when you didn't change documentation.
+    * - ``[skip appveyor]``
+      - Skip AppVeyor run.
+      - Substring must be in first line of commit message.
+    * - ``[skip azp]``
+      - Skip Azure Pipelines.
+      -
+    * - ``[skip actions]``
+      - Skip GitHub Actions
+      -
+    * - ``[skip ci]``
+      - Skip all CI checks.
+      - Use only for changes where documentation checks and unit tests do not apply.
+
+
+``[skip actions]`` and ``[skip ci]`` skip Github Actions CI workflows that are
+triggered on ``on: push`` and ``on: pull_request`` events. For more information,
+see `Skipping workflow runs`_.
 
 .. _`Skipping workflow runs`: https://docs.github.com/en/actions/managing-workflow-runs/skipping-workflow-runs
