docs: examples are not being uploaded as assets (.py/.ipynb) (#1268)

Co-authored-by: pyansys-ci-bot <pyansys.github.bot@ansys.com>

Author: RobPasMue

.github/workflows/ci_cd.yml

@@ -267,9 +267,28 @@ jobs:
       group: pyansys-self-hosted
       labels: [Windows, pygeometry]
     steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ env.MAIN_PYTHON_VERSION }}
+
       - name: Set up headless display
         uses: pyvista/setup-headless-display-action@v2
 
+      - name: Create Python venv
+        run: |
+          python -m venv .venv
+          .\.venv\Scripts\Activate.ps1
+
+      - name: Install packages for documentation build
+        run: |
+          .\.venv\Scripts\Activate.ps1
+          python -m pip install --upgrade pip
+          pip install --upgrade build wheel
+          pip install .[doc]
+
       - name: Login to GitHub Container Registry
         uses: docker/login-action@v3
         with:
@@ -285,14 +304,49 @@ jobs:
         run:
           echo "ANSRV_GEO_LICENSE_SERVER=${{ secrets.INTERNAL_LICENSE_SERVER }}" | Out-File -FilePath $env:GITHUB_ENV -Append
 
-      - name: Start Geometry service
-        run: docker run --detach --name ${{ env.GEO_CONT_NAME }} -e LICENSE_SERVER=${{ env.ANSRV_GEO_LICENSE_SERVER }} -p ${{ env.ANSRV_GEO_PORT }}:50051 ${{ env.ANSRV_GEO_IMAGE_WINDOWS_TAG }}
+      - name: Start Geometry service and verify start
+        run: |
+          .\.venv\Scripts\Activate.ps1
+          docker run --detach --name ${{ env.GEO_CONT_NAME }} -e LICENSE_SERVER=${{ env.ANSRV_GEO_LICENSE_SERVER }} -p ${{ env.ANSRV_GEO_PORT }}:50051 ${{ env.ANSRV_GEO_IMAGE_WINDOWS_TAG }}
+          python -c "from ansys.geometry.core.connection.validate import validate; validate()"
+
+      - name: Check links
+        run: |
+          .\.venv\Scripts\Activate.ps1
+          cd doc
+          .\make.bat linkcheck
+
+      - name: Build the documentation (HTML)
+        run: |
+          .\.venv\Scripts\Activate.ps1
+          cd doc
+          .\make.bat html
+
+      - name: Build the documentation (PDF)
+        run: |
+          .\.venv\Scripts\Activate.ps1
+          cd doc
+          .\make.bat pdf
+
+      - name: Add assets to HTML docs
+        run: |
+          zip -r documentation-html.zip .\doc\_build\html
+          mv documentation-html.zip .\doc\_build\html\_static\assets\download\
+          cp doc/_build/latex/ansys-geometry-core.pdf .\doc\_build\html\_static\assets\download\
 
-      - name: Run Ansys documentation building action
-        uses: ansys/actions/doc-build@v6
+      - name: Upload HTML documentation
+        uses: actions/upload-artifact@v4
         with:
-          python-version: ${{ env.MAIN_PYTHON_VERSION }}
-          add-pdf-html-docs-as-assets: true
+          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/ansys-geometry-core*.pdf
+          retention-days: 7
 
       - name: Stop the Geometry service
         if: always()
@@ -310,6 +364,7 @@ jobs:
               docker rm $dockerContainers
           }
 
+
 # =================================================================================================
 # ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^    RUNNING ON SELF-HOSTED RUNNER    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 # =================================================================================================

doc/Makefile

@@ -32,5 +32,8 @@ pdf:
 
 # Build HTML files and generate examples as .py files
 html:
-	@$(SPHINXBUILD) -M linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 	@$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+# Linkcheck
+linkcheck:
+	@$(SPHINXBUILD) -M linkcheck "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

doc/changelog.d/1268.fixed.md

@@ -0,0 +1 @@
+docs: examples are not being uploaded as assets (.py/.ipynb)

doc/make.bat

@@ -15,9 +15,11 @@ set APIDIR=api
 set BUILDDIR=_build
 
 if "%1" == "" goto help
+if "%1" == "help" goto help
 if "%1" == "clean" goto clean
 if "%1" == "pdf" goto pdf
 if "%1" == "html" goto html
+if "%1" == "linkcheck" goto linkcheck
 
 %SPHINXBUILD% >NUL 2>NUL
 if errorlevel 9009 (
@@ -35,9 +37,12 @@ if errorlevel 9009 (
 %SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
+:linkcheck
+%SPHINXBUILD% -M linkcheck %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
 :html
 %SPHINXBUILD% -M html %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
-%SPHINXBUILD% -M linkcheck %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
 goto end
 
 :pdf

doc/source/conf.py

@@ -18,9 +18,14 @@
 import requests
 import sphinx
 from sphinx.builders.latex import LaTeXBuilder
+from sphinx.util import logging
 
 from ansys.geometry.core import __version__
 
+# Convert notebooks into Python scripts and include them in the output files
+logger = logging.getLogger(__name__)
+
+
 # For some reason the global var is not working on doc build...
 # import ansys.tools.visualization_interface as viz_interface
 #
@@ -393,9 +398,15 @@ def convert_notebooks_to_scripts(app: sphinx.application.Sphinx, exception):
         import subprocess
 
         examples_output_dir = Path(app.outdir) / "examples"
+        if not examples_output_dir.exists():
+            logger.info("No examples directory found, skipping conversion...")
+            return
+
         notebooks = examples_output_dir.glob("**/*.ipynb")
+        count = 0
         for notebook in notebooks:
-            print(f"Converting {notebook}")  # using jupytext
+            count += 1
+            logger.info(f"Converting {notebook}")  # using jupytext
             output = subprocess.run(
                 [
                     "jupytext",
@@ -410,8 +421,13 @@ def convert_notebooks_to_scripts(app: sphinx.application.Sphinx, exception):
             )
 
             if output.returncode != 0:
-                print(f"Error converting {notebook} to script")
-                print(output.stderr)
+                logger.error(f"Error converting {notebook} to script")
+                logger.error(output.stderr)
+
+        if count == 0:
+            logger.warning("No notebooks found to convert to scripts")
+        else:
+            logger.info(f"Converted {count} notebooks to scripts")
 
 
 def setup(app: sphinx.application.Sphinx):
@@ -423,7 +439,8 @@ def setup(app: sphinx.application.Sphinx):
     app : sphinx.application.Sphinx
         Sphinx instance containing all the configuration for the documentation build.
     """
-    # Convert notebooks into Python scripts and include them in the output files
+    logger.info(f"Configuring Sphinx hooks...")
     if BUILD_EXAMPLES:
         # Run at the end of the build process
+        logger.info("Connecting build-finished hook for converting notebooks to scripts...")
         app.connect("build-finished", convert_notebooks_to_scripts)

pyproject.toml

@@ -30,7 +30,8 @@ dependencies = [
     "beartype>=0.11.0,<0.19",
     "grpcio>=1.35.0,<2",
     "grpcio-health-checking>=1.45.0,<2",
-    "numpy>=1.20.3,<3",
+    "numpy>=1.20.3,<3; python_version>='3.10'",
+    "numpy>=1.20.3,<2; python_version=='3.9'",       # Remove when Python 3.9 support is dropped
     "Pint>=0.18,<1",
     "protobuf>=3.20.2,<6",
     "pyvista>=0.37.0,<1",