ci(doc): add doc build examples caching (#2342)

Author: PProfizi

.github/workflows/docs.yml

@@ -117,26 +117,41 @@ jobs:
         run: |
           choco install pandoc
 
+      - name: "Restore doc build cache"
+        id: cache-doc-build-restore
+        uses: actions/cache/restore@v4
+        with:
+          path: |
+            doc/source/examples
+          # Cache key is composed of branch name, ansys version, hash of requirements_doc,
+          # and run_id to work around immutability
+          # We should also track version of pandoc, of graphviz, of packages installed by headless-display, and even of pydpf-core?
+          key: doc-build-${{ github.ref_name }}-DPF_${{inputs.ANSYS_VERSION}}${{inputs.standalone_suffix}}-${{hashfiles('requirements/requirements_docs.txt')}}-${{ github.run_id }}
+          restore-keys: |
+            doc-build-${{ github.ref_name }}-DPF_${{inputs.ANSYS_VERSION}}${{inputs.standalone_suffix}}-${{hashfiles('requirements/requirements_docs.txt')}}-
+            doc-build-master-DPF_${{inputs.ANSYS_VERSION}}${{inputs.standalone_suffix}}-${{hashfiles('requirements/requirements_docs.txt')}}-
+
       - name: "Build HTML Documentation"
         shell: bash
         run: |
           tox -e doc-html --installpkg dist/${{ steps.wheel.outputs.wheel_name }} -x testenv:doc-html.setenv+='VIRTUALENV_SYSTEM_SITE_PACKAGES=true'
 
-      - name: "Retrieve package version"
-        shell: bash
-        run: |
-          echo "VERSION=$(python -c "from ansys.dpf.${{env.MODULE}} import __version__; print(__version__)")" >> GITHUB_OUTPUT
-          echo "${{env.PACKAGE_NAME}} version is: $(python -c "from ansys.dpf.${{env.MODULE}} import __version__; print(__version__)")"
-        id: version
-        if: always()
-
       - name: "Upload Documentation Build log"
         uses: actions/upload-artifact@v4
         with:
           name: doc-${{env.PACKAGE_NAME}}-log
           path: doc/*.txt
         if: always()
 
+      - name: "Save doc-build cache"
+        id: cache-doc-build-save
+        uses: actions/cache/save@v4
+        with:
+          path: |
+            doc/build
+            doc/source/examples
+          key: ${{ steps.cache-doc-build-restore.outputs.cache-primary-key }}
+
       - name: "Zip HTML Documentation"
         shell: pwsh
         run: |

doc/source/conf.py

@@ -1,6 +1,7 @@
 from datetime import datetime
 from glob import glob
 import os
+import sys
 from pathlib import Path
 import subprocess
 
@@ -16,6 +17,9 @@
 from ansys.dpf.core import __version__, server, server_factory
 from ansys.dpf.core.examples import get_example_required_minimum_dpf_version
 
+# Make sphinx_utilities modules importable
+sys.path.append(os.path.join(os.path.dirname(__file__), "../sphinx_utilities"))
+
 # Manage errors
 pyvista.set_error_output_file("errors.txt")
 # Ensure that offscreen rendering is used for docs generation
@@ -56,12 +60,13 @@
 server_version = server_instance.version
 server.shutdown_all_session_servers()
 print(f"DPF version: {server_version}")
+print(f"DPF install: {server_instance.ansys_path}")
 
 # Build ignore pattern
 ignored_pattern = r"(ignore"
 header_flag = "\"\"\""
 note_flag = r".. note::"
-for example in glob(r"../../examples/**/*.py"):
+for example in sorted(glob(r"../../examples/**/*.py")):
     minimum_version_str = get_example_required_minimum_dpf_version(example)
     if float(server_version) - float(minimum_version_str) < -0.05:
         example_name = example.split(os.path.sep)[-1]
@@ -124,8 +129,7 @@
 typehints_defaults = "comma"
 typehints_use_signature = True
 simplify_optional_unions = False
-suppress_warnings = ['autosectionlabel.*']
-
+autosectionlabel_prefix_document = True
 # Intersphinx mapping
 intersphinx_mapping = {
     "pyvista": ("https://docs.pyvista.org/", None),
@@ -163,32 +167,6 @@
 
 
 # -- Sphinx Gallery Options
-from sphinx_gallery.sorting import FileNameSortKey
-
-
-def reset_servers(gallery_conf, fname, when):
-    import gc
-
-    import psutil
-
-    from ansys.dpf.core import server
-
-    gc.collect()
-    server.shutdown_all_session_servers()
-
-    proc_name = "Ans.Dpf.Grpc"
-    nb_procs = 0
-    for proc in psutil.process_iter():
-        try:
-            # check whether the process name matches
-            if proc_name in proc.name():
-                proc.kill()
-                nb_procs += 1
-        except psutil.NoSuchProcess:
-            pass
-    print(f"Counted {nb_procs} {proc_name} processes {when} example {fname}.")
-
-
 sphinx_gallery_conf = {
     # convert rst to md for ipynb
     "pypandoc": True,
@@ -205,15 +183,15 @@ def reset_servers(gallery_conf, fname, when):
     # Remove the "Download all examples" button from the top level gallery
     "download_all_examples": False,
     # Sort gallery example by file name instead of number of lines (default)
-    "within_subsection_order": FileNameSortKey,
+    "within_subsection_order": "FileNameSortKey",
     # directory where function granular galleries are stored
     "backreferences_dir": None,
     "image_scrapers": ("pyvista", "matplotlib"),
     # 'first_notebook_cell': ("%matplotlib inline\n"
     #                         "from pyvista import set_plot_theme\n"
     #                         "set_plot_theme('document')"),
     "reset_modules_order": 'both',
-    "reset_modules": (reset_servers,),
+    "reset_modules": ("reset_servers.reset_servers",),
 }
 
 
@@ -272,6 +250,9 @@ def reset_servers(gallery_conf, fname, when):
     "design.grid",
     "config.cache",
     "design.fa-build",
+    "autosectionlabel.*",
+    "ref.python",
+    "toc.not_included"
 ]
 
 # Add any paths that contain custom static files (such as style sheets) here,
@@ -405,4 +386,4 @@ def reset_servers(gallery_conf, fname, when):
 
 BUILD_EXAMPLES = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False
 if BUILD_EXAMPLES:
-    extensions.extend(["sphinx_gallery.gen_gallery"])
+    extensions.extend(["sphinx_gallery.gen_gallery"])

doc/sphinx_utilities/reset_servers.py

@@ -0,0 +1,22 @@
+#
+def reset_servers(gallery_conf, fname, when):
+    import gc
+
+    import psutil
+
+    from ansys.dpf.core import server
+
+    gc.collect()
+    server.shutdown_all_session_servers()
+
+    proc_name = "Ans.Dpf.Grpc"
+    nb_procs = 0
+    for proc in psutil.process_iter():
+        try:
+            # check whether the process name matches
+            if proc_name in proc.name():
+                proc.kill()
+                nb_procs += 1
+        except psutil.NoSuchProcess:
+            pass
+    print(f"Counted {nb_procs} {proc_name} processes {when} example {fname}.")

requirements/requirements_docs.txt

@@ -1,4 +1,4 @@
-ansys-sphinx-theme[autoapi]==1.4.4
+ansys-sphinx-theme[autoapi]==1.5.3
 enum-tools[sphinx]==0.13.0
 graphviz==0.21
 imageio==2.37.0

tox.ini

@@ -227,7 +227,7 @@ commands =
     # Remove previously rendered documentation
     clean: python -c "import shutil, sys; shutil.rmtree(sys.argv[1], ignore_errors=True)" "{toxinidir}/{env:BUILD_DIR}"
 
-    # Clean files from previous build
+    # Clean examples from previous build
     clean: python -c "\
     clean: from os.path import exists; import shutil; \
     clean: [(shutil.rmtree(p) if exists(p) else None) for p in ['{env:SOURCE_DIR}/images/auto-generated']]; \