turn ci information into tables

story645 · story645 · commit 252dd92c57c7 · 2024-01-25T20:41:30.000-05:00
diff --git a/doc/devel/development_workflow.rst b/doc/devel/development_workflow.rst
@@ -466,40 +466,65 @@ 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::
+    :stub-columns: 1
+    :widths: 20 15 65
+
+    * - 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
+      - Unit tests
+      - | Search the log for ``FAILURES``. Subsequent section should contain information
+          on failed tests.
+        | On Azure, 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*.
 
 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::
+    :stub-columns: 1
+    :widths: 25 20 55
+
+    * - ``[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 circle]``
+      - 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
