Merge remote-tracking branch 'origin/doc/jupyter_examples' into doc/jupyter_examples

Author: Devin-Crawford

.github/workflows/build_documentation.yml

@@ -74,8 +74,7 @@ jobs:
 
       - name: Install doc build requirements
         run: |
-          sudo apt install graphviz
-          sudo apt install -y pandoc
+          sudo apt install -y graphviz pandoc
 
       # run doc build, without creating the examples directory
       # note that we have to add the examples file here since it won't

doc/source/User_guide/pyaedt_file_data/project.rst

@@ -33,7 +33,7 @@ File structure examples:
 
 :download:`HFSS 3D Layout Example <../../Resources/hfss3dlayout_project_example.json>`
 
-.. code-block:: json
+.. code-block::
 
     {
         "general": {

doc/source/conf.py

@@ -117,7 +117,7 @@ def remove_examples(app, exception):
     DESTINATION_DIRECTORY = pathlib.Path(app.srcdir) / "examples"
     size = directory_size(DESTINATION_DIRECTORY)
     logger.info(f"Removing directory {DESTINATION_DIRECTORY} ({size} MB).")
-    shutil.rmtree(DESTINATION_DIRECTORY)
+    shutil.rmtree(DESTINATION_DIRECTORY, ignore_errors=True)
     logger.info(f"Directory removed.")
 
 def add_ipython_time(app, docname, source):
@@ -201,6 +201,22 @@ def remove_ipython_time_from_html(app, pagename, templatename, context, doctree)
         pattern = r'<span class="o">%%time<\/span>\n'
         context['body'] = re.sub(pattern, '', context['body'])  
 
+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 error in html-page-context')
 
 def setup(app):
     app.add_directive('pprint', PrettyPrintDirective)
@@ -209,8 +225,10 @@ def setup(app):
     app.connect('source-read', add_ipython_time)
     app.connect('source-read', adjust_image_path)
     app.connect('html-page-context', remove_ipython_time_from_html)
+    app.connect('html-page-context', check_example_error)
     app.connect('build-finished', remove_examples)
     app.connect('build-finished', remove_doctree)
+    app.connect('build-finished', check_build_finished_without_error)
 
 local_path = os.path.dirname(os.path.realpath(__file__))
 module_path = pathlib.Path(local_path)

examples/Readme.txt renamed to examples/index.rst

@@ -1,4 +1,10 @@
-.. _ref_example_gallery:
+.. _ref_examples:
+
+.. toctree::
+   :hidden:
+   :maxdepth: 2
+
+   00-EDB/index
 
 Examples
 ========