Feat/improve doc build logic

.github/workflows/ci_cd.yml

@@ -101,13 +101,6 @@ jobs:
           path: doc/_build/html
           retention-days: 7
 
-      - name: Upload PDF Documentation
-        uses: actions/upload-artifact@v4
-        with:
-          name: documentation-pdf
-          path: doc/_build/latex/*.pdf
-          retention-days: 7
-
   smoke-tests:
     name: Build and Smoke tests
     runs-on: ${{ matrix.os }}

.github/workflows/nightly.yml

@@ -130,10 +130,3 @@ jobs:
           name: documentation-html
           path: doc/_build/html
           retention-days: 7
-
-      - name: Upload PDF Documentation
-        uses: actions/upload-artifact@v4
-        with:
-          name: documentation-pdf
-          path: doc/_build/latex/*.pdf
-          retention-days: 7        

doc/source/conf.py

@@ -1,15 +1,66 @@
 # Sphinx documentation configuration file
 from datetime import datetime
 import os
-import pathlib
+from pathlib import Path
 import shutil
 import sys
+from zipfile import ZipFile
 
 from ansys_sphinx_theme import ansys_favicon, get_version_match, pyansys_logo_black
 import sphinx
 
 from ansys.hps.client import __version__
 
+# Constants declaration
+EXAMPLES = {
+    "mapdl_motorbike_frame": [
+        "project_setup.py",
+        "project_query.py",
+        "exec_mapdl.py",
+        "motorbike_frame_results.txt",
+        "motorbike_frame.mac",
+    ],
+    "mapdl_tyre_performance": [
+        "project_setup.py",
+        "tire_performance_simulation.mac",
+        "2d_tire_geometry.iges",
+    ],
+    "mapdl_linked_analyses": [
+        "project_setup.py",
+        "prestress.dat",
+        "modal.dat",
+        "harmonic.dat",
+    ],
+    "lsdyna_cylinder_plate": [
+        "lsdyna_job.py",
+        "cylinder_plate.k",
+        "postprocess.cfile",
+    ],
+    "python_two_bar_truss_problem": [
+        "project_setup.py",
+        "exec_python.py",
+        "evaluate.py",
+        "input_parameters.json",
+    ],
+    "fluent_2d_heat_exchanger": [
+        "project_setup.py",
+        "heat_exchanger.jou",
+        "heat_exchanger.cas.h5",
+    ],
+    "fluent_nozzle": [
+        "project_setup.py",
+        "solve.jou",
+        "nozzle.cas",
+    ],
+    "cfx_static_mixer": [
+        "project_setup.py",
+        "exec_cfx.py",
+        "runInput.ccl",
+        "StaticMixer_001.cfx",
+        "StaticMixer_001.def",
+    ],
+}
+
 sys.path.append(os.path.abspath(os.path.dirname(__file__)))
 
 # -- Project information -----------------------------------------------------
@@ -332,9 +383,9 @@ def prepare_jinja_env(jinja_env) -> None:
 }
 
 
-def copy_download_files_to_source_dir(app: sphinx.application.Sphinx) -> None:
+def archive_examples(app: sphinx.application.Sphinx) -> None:
     """
-    Copy zipped example files to target directory at build time
+    Create a zip archive for each listed example included in the examples folder.
 
     Parameters
     ----------
@@ -343,16 +394,28 @@ def copy_download_files_to_source_dir(app: sphinx.application.Sphinx) -> None:
 
     """
 
-    # archive_examples.py in the root directory is being run before doc build (via tox)
-    # we simply need to copy the into the _download target defined in the .rst source files.
-    SOURCE_DIR = pathlib.Path(app.srcdir)
-    ZIPPED_FILES_DIR = SOURCE_DIR.parent.parent / "build"
-    DOWNLOAD_FILES_DIR = SOURCE_DIR.parent / "_build" / "html" / "_downloads"
-    DOWNLOAD_FILES_DIR.mkdir(exist_ok=True)
-
-    for file_path in ZIPPED_FILES_DIR.glob("*"):
+    source_dir = Path(app.srcdir)
+    root_path = source_dir.parent.parent
+
+    # Create zip files for each example
+    build_path = root_path / "build"
+    build_path.mkdir(exist_ok=True)
+    for name, files in EXAMPLES.items():
+        with ZipFile(build_path / f"{name}.zip", "w") as zip_archive:
+            for file in files:
+                zip_archive.write(root_path / "examples" / name / file, file)
+
+    with ZipFile(build_path / "pyhps_examples.zip", "w") as zip_archive:
+        for name, files in EXAMPLES.items():
+            for file in files:
+                zip_archive.write(root_path / "examples" / name / file, Path(name) / file)
+
+    # Copy zipped example files to target directory at build time
+    download_files_dir = source_dir.parent / "_build" / "html" / "_downloads"
+    download_files_dir.mkdir(exist_ok=True)
+    for file_path in build_path.glob("*"):
         if file_path.is_file():
-            shutil.copy(file_path, DOWNLOAD_FILES_DIR)
+            shutil.copy(file_path, download_files_dir)
 
 
 def setup(app: sphinx.application.Sphinx) -> None:
@@ -365,4 +428,4 @@ def setup(app: sphinx.application.Sphinx) -> None:
         Sphinx application instance containing the all the doc build configuration.
     """
 
-    app.connect("builder-inited", copy_download_files_to_source_dir)
+    app.connect("builder-inited", archive_examples)

tox.ini

@@ -44,6 +44,4 @@ deps =
     -e .[doc]
 allowlist_externals = make
 commands =
-    python archive_examples.py
-    make -C doc html
-    make -C doc pdf
+    sphinx-build -M html "{toxinidir}/doc/source" "{toxinidir}/doc/_build" -j auto