DOCS: Refactor examples (#1260)

Co-authored-by: pyansys-ci-bot <[email protected]>

Author: dipinknair

.github/workflows/ci_cd.yml

@@ -642,55 +642,28 @@ jobs:
           ANSYS_WORKBENCH_LOGGING_FILTER_LEVEL: 0
         run: |
           . /env/bin/activate
-          # Make html or pdf doc
-          make_doc() {
-            # $1 is the type of file we are creating (html or pdf)
 
-            # Need to unset PYMECHANICAL_PORT and PYMECHANICAL_START_INSTANCE when running code containing remote sessions
-            unset PYMECHANICAL_PORT
-            unset PYMECHANICAL_START_INSTANCE
+          apt update
+          apt install -y libjbig-dev
+          # Add the /usr/lib/x86_64-linux-gnu/ path to the LD_LIBRARY_PATH (where libjbig-dev .so files are)
+          export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/x86_64-linux-gnu/
 
-            output_file=doc_$1_output.txt
-            if [ "${{ needs.container-stability-check.outputs.container_stable_exit }}" = "true" ]; then
-              xvfb-run mechanical-env make -C doc $1
-            else
-              xvfb-run mechanical-env make -C doc $1 > $output_file 2>&1 || true
-              cat $output_file
-              echo done running make
-              validate_output $output_file
-            fi
-          }
-
-          # Validate that the html or pdf build succeeded
-          validate_output() {
-            echo "validating output of build"
-            # $1 is the file we are checking
-            # cat $1
-            #
-            # Check if "build succeeded" string is present in doc_build_output.txt
-            #
-            if grep -q "build succeeded" $1; then
+          if [ "${{ needs.container-stability-check.outputs.container_stable_exit }}" = "true" ]; then
+            xvfb-run mechanical-env make -C doc html
+          else
+            xvfb-run mechanical-env make -C doc html > output.txt 2>&1 || true
+            cat output.txt
+            if grep -q "build succeeded" output.txt; then
               echo "Documentation building succeeded"
             else
               echo "Documentation building failed"
               exit 1
             fi
-          }
-
-          # Install libjbig-dev so quarto doesn't fail its PDF build on v242
-          apt update
-          apt install -y libjbig-dev
-          # Add the /usr/lib/x86_64-linux-gnu/ path to the LD_LIBRARY_PATH (where libjbig-dev .so files are)
-          export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/lib/x86_64-linux-gnu/
-
-          # Make the html doc & validate results
-          make_doc html
-
-          # Make the pdf doc & validate results
-          make_doc pdf
-
-          # Make the pdf doc & validate results
-          make_doc linkcheck
+          fi
+      - name: Check links
+        run: |
+          . /env/bin/activate
+          make -C doc linkcheck
 
       - name: Upload HTML Documentation
         uses: actions/upload-artifact@v4
@@ -699,13 +672,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
-
   coverage:
     name: Merging coverage
     needs: [remote-connect, embedding-tests, embedding-scripts-tests, launch-tests]

.gitignore

@@ -199,7 +199,7 @@ doc/source/api/*
 !doc/source/api/path.rst
 
 # Examples files downloaded when building docs
-examples/embedding_n_remote/download/*
+examples/01_basic/out/*
 
 # pymechanical-specific
 mylocal.ip

.pre-commit-config.yaml

@@ -63,7 +63,7 @@ repos:
           tests/scripts/run_python_error.py |
           tests/scripts/run_python_success.py |
           tests/scripts/log_message.py |
-          examples/embedding_n_remote/embedding_remote.py
+          examples/.*$
         )$
 
 - repo: https://github.com/pre-commit/pre-commit-hooks

doc/changelog.d/1260.documentation.md

@@ -0,0 +1 @@
+Refactor examples

doc/source/conf.py

@@ -13,6 +13,8 @@
 import warnings
 
 from ansys_sphinx_theme import ansys_favicon, get_version_match
+import pyvista
+from pyvista.plotting.utilities.sphinx_gallery import DynamicScraper
 from sphinx_gallery.sorting import FileNameSortKey
 
 import ansys.mechanical.core as pymechanical
@@ -21,6 +23,13 @@
 # necessary when building the sphinx gallery
 pymechanical.BUILDING_GALLERY = True
 
+# Ensure that offscreen rendering is used for docs generation
+pyvista.OFF_SCREEN = True
+
+# necessary when building the sphinx gallery
+pyvista.BUILDING_GALLERY = True
+
+
 # Whether or not to build the cheatsheet
 BUILD_CHEATSHEET = True if os.environ.get("BUILD_EXAMPLES", "true") == "true" else False
 
@@ -60,6 +69,8 @@
     "sphinx_autodoc_typehints",
     "sphinx_copybutton",
     "sphinx_design",
+    "pyvista.ext.plot_directive",
+    "pyvista.ext.viewer_directive",
 ]
 
 if pymechanical.BUILDING_GALLERY:
@@ -175,8 +186,7 @@
     # path to your examples scripts
     "examples_dirs": ["../../examples/"],
     # path where to save gallery generated examples
-    "gallery_dirs": ["examples/gallery_examples"],
-    # Pattern to search for example files
+    "gallery_dirs": ["examples/gallery_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,
@@ -186,7 +196,7 @@
     "backreferences_dir": None,
     # Modules for which function level galleries are created.  In
     "doc_module": "ansys-mechanical-core",
-    "image_scrapers": ("matplotlib"),
+    "image_scrapers": (DynamicScraper(), "matplotlib"),
     "ignore_pattern": "flycheck*",
     "thumbnail_size": (350, 350),
 }
@@ -229,7 +239,6 @@
         "sidebar_pages": ["changelog", "index"],
     },
     "ansys_sphinx_theme_autoapi": {"project": project, "templates": "_templates/autoapi"},
-    "navigation_depth": 10,
 }
 
 if BUILD_CHEATSHEET:
@@ -245,7 +254,6 @@
 
 html_sidebars = {
     "changelog": [],
-    "examples/index": [],
     "contributing": [],
 }
 

doc/source/examples/advanced_examples/index.rst

@@ -0,0 +1,8 @@
+.. _ref_remote_examples:
+
+Advanced Examples
+-----------------
+
+This section contains examples that demonstrates advanced capabilities of Mechanical
+using Pymechanical.
+For more information, see `Advanced examples <pymechanical_embedding_ex_basic_>`_.

doc/source/examples/index.rst

@@ -1,30 +1,41 @@
 .. _ref_examples:
 
+========
 Examples
 ========
 
-Here are examples using Mechanical with the ``ansys-mechanical-core`` library through
-an embedded instance or remote session.
+Here is a series of examples using Mechanical with the ``ansys-mechanical-core`` library.
+
+.. === EXAMPLES Gallery ===
+
+..
+   We have to include this rather than include it in a tree.
+
+.. include:: gallery_examples/index.rst
+   :start-line: 2
+
+
+.. === ADVANCED EXAMPLES ===
+
+.. toctree::
+    :hidden:
+    :maxdepth: 3
+
+    Advanced Examples <https://embedding.examples.mechanical.docs.pyansys.com/examples/index.html>
 
-.. grid:: 1 2 2 2
 
-   .. grid-item-card:: Embedding Examples
-      :padding: 2 2 2 2
-      :link: https://embedding.examples.mechanical.docs.pyansys.com/examples/index.html
+.. include:: advanced_examples/index.rst
+   :start-line: 2
 
-      Uses PyMechanical to embed an instance of Mechanical directly within Python as a Python object.
 
-   .. grid-item-card:: Remote Session Examples
-      :padding: 2 2 2 2
-      :link: https://examples.mechanical.docs.pyansys.com/examples/index.html
+.. === REMOTE EXAMPLES ===
 
-      Uses PyMechanical as a client to a remote Mechanical instance.
+.. toctree::
+    :hidden:
+    :maxdepth: 3
 
-.. grid:: 1
+    Remote Sessions <https://examples.mechanical.docs.pyansys.com/index.html>
 
-   .. grid-item-card:: Embedding Instance & Remote Session Example
-      :padding: 2 2 2 2
-      :link: gallery_examples/embedding_n_remote/embedding_remote.html
 
-      Demonstrates the same model setup in both an embedded instance and remote session,
-      as well as examples using a combination of embedded instances and remote sessions.
+.. include:: remote_examples/index.rst
+   :start-line: 2

doc/source/examples/remote_examples/index.rst

@@ -0,0 +1,8 @@
+.. _ref_remote_session_examples:
+
+Remote examples
+---------------
+
+Remote examples demonstrate the basic simulation capabilities of Mechanical using remote sessions.
+
+For more information, see `Remote sessions examples <pymechanical_remote_ex_all_>`_.

doc/source/user_guide_session/index.rst

@@ -16,7 +16,6 @@ to a remote Mechanical session.
 
    self
    server-launcher
-   mechanical
    pool
 
 Overview