Use the gallery to generate the Verification Manual examples

.github/workflows/ci_cd.yml

@@ -13,6 +13,8 @@ on:
 
 env:
   MAIN_PYTHON_VERSION: '3.9'
+  RESET_EXAMPLES_CACHE: 0
+  RESET_DOC_BUILD_CACHE: 0
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -40,27 +42,18 @@ jobs:
       - name: Test with tox
         run: tox -e style
 
-  # docs-style:
-  #   name: Documentation Style Check
-  #   runs-on: ubuntu-latest
-  #   steps:
-  #     - uses: actions/checkout@v3
-
-  #     - name: Running Vale
-  #       uses: errata-ai/vale-action@reviewdog
-  #       env:
-  #         GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
-  #       with:
-  #         files: doc
-  #         reporter: github-pr-check
-  #         level: error
-  #         filter_mode: nofilter
-  #         fail_on_error: true
-  #         vale_flags: "--config=doc/.vale.ini"
-
-  docs:
-    name: Documentation
-    needs: [style]  #docs-style
+  doc-style:
+    name: Documentation Style Check
+    runs-on: ubuntu-latest
+    steps:
+      - name: PyAnsys documentation style checks
+        uses: pyansys/actions/doc-style@v3
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+
+  doc-build:
+    name: Documentation building
+    needs: [style, doc-style]
     runs-on: ubuntu-latest
     env:
       PYMAPDL_PORT: 21000  # default won't work on GitHub runners
@@ -71,7 +64,8 @@ jobs:
       DPF_PORT: 21002
 
     steps:
-      - uses: actions/checkout@v3
+      - name: "Install Git and checkout project"
+        uses: actions/checkout@v3
 
       - name: "Set up Python using cache"
         uses: actions/setup-python@v4
@@ -97,7 +91,7 @@ jobs:
         uses: docker/login-action@v2.1.0
         with:
           registry: ghcr.io
-          username: ${{ github.actor }}
+          username: ${{ secrets.GH_USERNAME }}
           password: ${{ secrets.GITHUB_TOKEN }}
 
       - name: Pull, launch, and validate MAPDL service
@@ -108,18 +102,40 @@ jobs:
 
       - name: Retrieve PyMAPDL version
         run: |
-          echo "{PYMAPDL_VERSION}={$(python -c 'from ansys.mapdl.core import __version__; print(__version__)')}" >> $GITHUB_OUTPUT
+          echo "PYMAPDL_VERSION=$(python -c 'from ansys.mapdl.core import __version__; print(__version__)')" >> $GITHUB_ENV
           echo "PyMAPDL version is: $(python -c "from ansys.mapdl.core import __version__; print(__version__)")"
         id: version
-      
+
       - name: DPF Server Activation
         run: |
           docker pull ghcr.io/pyansys/dpf-core:22.2dev
           docker run -d --name dpfserver -p ${{ env.DPF_PORT }}:50052 ghcr.io/pyansys/dpf-core:22.2dev && echo "DPF Server active on port ${{ env.DPF_PORT }}."
 
-      - name: Build Documentation
-        run: |
-          xvfb-run make -C doc html SPHINXOPTS="-j auto -W --keep-going"
+      - name: "Cache Verification Manual examples"
+        uses: actions/cache@v3
+        with:
+          path: doc/source/verif-manual
+          key: Examples-v${{ env.RESET_EXAMPLES_CACHE }}-${{ env.PYMAPDL_VERSION }}-${{ github.sha }}
+          restore-keys: |
+            Examples-v${{ env.RESET_EXAMPLES_CACHE }}-${{ env.PYMAPDL_VERSION }}
+
+      - name: "Cache docs build directory"
+        uses: actions/cache@v3
+        with:
+          path: doc/_build
+          key: doc-build-v${{ env.RESET_DOC_BUILD_CACHE }}-${{ env.PYMAPDL_VERSION }}-${{ github.sha }}
+          restore-keys: |
+            doc-build-v${{ env.RESET_DOC_BUILD_CACHE }}-${{ env.PYMAPDL_VERSION }}
+
+      - name: "Run Ansys documentation building action"
+        uses: pyansys/actions/doc-build@v3
+        with:
+          requires-xvfb: true
+          python-version: ${{ env.MAIN_PYTHON_VERSION }}
+          checkout: false
+          skip-install: true
+          sphinxopts: -j auto
+          use-python-cache: False
 
       - name: Upload HTML Documentation
         uses: actions/upload-artifact@v3
@@ -200,7 +216,7 @@ jobs:
 
   release:
     if: github.event_name == 'push' && contains(github.ref, 'refs/tags')
-    needs: [style, docs] #docs-style
+    needs: [style, doc-build] #docs-style
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v3

.gitignore

@@ -74,6 +74,7 @@ instance/
 
 # Sphinx documentation
 doc/_build/
+doc/source/verif-manual/*
 
 # PyBuilder
 .pybuilder/

README.rst

@@ -1,7 +1,7 @@
 PyMAPDL Examples
 ================
 
-Repository holding examples for PyMAPDL.
+This repository holds examples for PyMAPDL.
 
 
 How to install

doc/.vale.ini

@@ -5,7 +5,7 @@
 StylesPath = "styles"
 
 # The options are `suggestion`, `warning`, or `error` (defaults to “warning”).
-MinAlertLevel = warning
+MinAlertLevel = error
 
 # By default, `code` and `tt` are ignored.
 IgnoredScopes = code, tt

doc/Makefile

@@ -14,7 +14,7 @@ help:
 .PHONY: help Makefile
 
 # Catch-all target: route all unknown targets to Sphinx using the new
-# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
 %: Makefile
 	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
 

doc/source/conf.py

@@ -1,7 +1,12 @@
 """Sphinx documentation configuration file."""
 from datetime import datetime
+import os
 
+from ansys.mapdl import core as pymapdl
 from ansys_sphinx_theme import pyansys_logo_black as logo
+import numpy as np
+import pyvista
+from sphinx_gallery.sorting import FileNameSortKey
 
 # Project information
 project = "pymapdl-examples"
@@ -22,7 +27,7 @@
     "additional_breadcrumbs": [
         ("PyAnsys", "https://docs.pyansys.com/"),
         ("PyMAPDL", "https://mapdl.docs.pyansys.com/"),
-        ("Examples", "https://mapdl.docs.pyansys.com/examples/"),
+        ("Examples", "https://mapdl.docs.pyansys.com/dev/examples/index.html"),
     ],
     "icon_links": [
         {
@@ -54,16 +59,18 @@
     # convert rst to md for ipynb
     "pypandoc": True,
     # path to your examples scripts
-    "examples_dirs": [],
+    "examples_dirs": ["../../examples/verif-manual"],
     # path where to save gallery generated examples
     "gallery_dirs": ["verif-manual", "technology_showcase_examples"],
     # Pattern to search for example files
     "filename_pattern": r"\.py",
     # 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,
     # directory where function granular galleries are stored
     "backreferences_dir": None,
-    # Modules for which function level galleries are created.  In
+    # Modules for which function level galleries are created. In
     "doc_module": "ansys-mapdl-core",
     "image_scrapers": ("pyvista", "matplotlib"),
     "ignore_pattern": "flycheck*",
@@ -83,7 +90,9 @@
 }
 
 # numpydoc configuration
+numpydoc_use_plots = True
 numpydoc_show_class_members = False
+numpydoc_class_members_toctree = False
 numpydoc_xref_param_type = True
 
 # Image referencing
@@ -107,6 +116,24 @@
     # type, unless multiple values are being returned"
 }
 
+# Manage errors
+pyvista.set_error_output_file("errors.txt")
+
+# Ensure that offscreen rendering is used for docs generation
+pyvista.OFF_SCREEN = True
+
+# must be less than or equal to the XVFB window size
+pyvista.rcParams["window_size"] = np.array([1024, 768])
+
+# Save figures in specified directory
+pyvista.FIGURE_PATH = os.path.join(os.path.abspath("./images/"), "auto-generated/")
+if not os.path.exists(pyvista.FIGURE_PATH):
+    os.makedirs(pyvista.FIGURE_PATH)
+
+
+# necessary when building the sphinx gallery
+pyvista.BUILDING_GALLERY = True
+pymapdl.BUILDING_GALLERY = True
 
 # static path
 html_static_path = ["_static"]