DOC: use pypandoc-binary while building documentation

.github/workflows/ci_cd.yml

@@ -73,6 +73,16 @@ jobs:
           pip install .
           pip install .[doc]
 
+      - name: Uninstall conflicting CI packages
+        run: |
+          .venv\Scripts\Activate.ps1
+          pip uninstall vtk pypandoc -y
+
+      - name: Install CI related dependencies
+        run: |
+          .venv\Scripts\Activate.ps1
+          pip install --extra-index-url https://wheels.vtk.org .[ci]
+
       - name: Retrieve common toolkit version
         run: |
           . .venv\Scripts\Activate.ps1

doc/source/conf.py

@@ -33,14 +33,69 @@
 from ansys_sphinx_theme import latex
 from ansys_sphinx_theme import pyansys_logo_black
 from ansys_sphinx_theme import watermark
+from sphinx.util import logging
 
-sys.path.append(str(pathlib.Path(__file__).parent.parent.parent))
+root_path = str(pathlib.Path(__file__).parent.parent.parent)
 
-path = os.path.join(pathlib.Path(__file__).parent.parent.parent, "src")
-print(path)
-sys.path.append(path)
+try:
+    from ansys.aedt.toolkits.common import __version__
+except ImportError:
+    sys.path.append(root_path)
+    src_path = os.path.join(root_path, "src")
+    sys.path.append(src_path)
+    from ansys.aedt.toolkits.common import __version__
+
+logger = logging.getLogger(__name__)
+path = pathlib.Path(os.path.join(root_path, "examples"))
+EXAMPLES_DIRECTORY = path.resolve()
+
+# Sphinx event hooks
+
+
+def check_example_error(app, pagename, templatename, context, doctree):
+    """Log an error if the execution of an example as a notebook triggered an error.
+
+    Since the documentation build might not stop if the execution of a notebook triggered
+    an error, we use a flag to log that an error is spotted in the html page context.
+    """
+    # Check if the HTML contains an error message
+    if pagename.startswith("examples") and not pagename.endswith("/index"):
+        if any(
+            map(
+                lambda msg: msg in context["body"],
+                ["UsageError", "NameError", "DeadKernelError", "NotebookError"],
+            )
+        ):
+            logger.error(f"An error was detected in file {pagename}")
+            app.builder.config.html_context["build_error"] = True
+
+
+def check_build_finished_without_error(app, exception):
+    """Check that no error is detected along the documentation build process."""
+    if app.builder.config.html_context.get("build_error", False):
+        raise Exception("Build failed due to an error in html-page-context")
+
+
+def check_pandoc_installed(app):
+    """Ensure that pandoc is installed"""
+    import pypandoc
+
+    try:
+        pandoc_path = pypandoc.get_pandoc_path()
+        pandoc_dir = os.path.dirname(pandoc_path)
+        if pandoc_dir not in os.environ["PATH"].split(os.pathsep):
+            logger.info("Pandoc directory is not in $PATH.")
+            os.environ["PATH"] += os.pathsep + pandoc_dir
+            logger.info(f"Pandoc directory '{pandoc_dir}' has been added to $PATH")
+    except OSError:
+        logger.error("Pandoc was not found, please add it to your path or install pypandoc-binary")
+
+
+def setup(app):
+    app.connect("builder-inited", check_pandoc_installed)
+    app.connect("html-page-context", check_example_error)
+    app.connect("build-finished", check_build_finished_without_error)
 
-from ansys.aedt.toolkits.common import __version__
 
 print(__version__)
 # Project information

pyproject.toml

@@ -60,6 +60,12 @@ doc = [
     "jupytext",
     "ipython==8.16.1",
     "jupyterlab==4.0.6",
+    "pypandoc",
+    "vtk==9.2.6",
+]
+ci = [
+    "pypandoc-binary==1.13",
+    "vtk-osmesa==9.2.20230527.dev0",
 ]
 
 [tool.flit.module]