DOC: leverage pypandoc-binary

Note: the idea is to be able to work with new self hosted runners
without having to install pandoc manually everytime.
Here, we leverage pypandoc-binary to use pandoc without installing
it before running the documentation. A sphinx even hook is
used to update the PATH environment variable if needed.

.github/workflows/ci_cd.yml

@@ -67,11 +67,12 @@ jobs:
           python -m pip install wheel setuptools -U
           python -c "import sys; print(sys.executable)"
 
-      - name: Install common toolkit with doc dependencies
+      - name: Install common toolkit with doc and ci dependencies
         run: |
           . .venv\Scripts\Activate.ps1
           pip install .
           pip install .[doc]
+          pip install .[ci]
 
       - name: Retrieve common toolkit version
         run: |

doc/source/conf.py

@@ -33,14 +33,64 @@
 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"])):
+            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,10 @@ doc = [
     "jupytext",
     "ipython==8.16.1",
     "jupyterlab==4.0.6",
+    "pypandoc",
+]
+ci = [
+    "pypandoc-binary==1.13",
 ]
 
 [tool.flit.module]