diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml index 7abc944f..1058d5c3 100644 --- a/.github/workflows/ci_cd.yml +++ b/.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 diff --git a/doc/source/conf.py b/doc/source/conf.py index b937c10a..e3b476b3 100644 --- a/doc/source/conf.py +++ b/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 diff --git a/pyproject.toml b/pyproject.toml index 1215f270..feb0d931 100644 --- a/pyproject.toml +++ b/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]