DOC: Avoid running examples twice (#26)

* DOC: Avoid running examples twice

* CI: Add ON_CI environment variable

* DOC: Only keep doctree to shorten CI/CD

* CI: Use env var SPHINXBUILD_KEEP_DOCTREEDIR

* REFACT: Update comment

Co-authored-by: Devin <38879940+dcrawforAtAnsys@users.noreply.github.com>

---------

Co-authored-by: Devin <38879940+dcrawforAtAnsys@users.noreply.github.com>

.github/workflows/ci_cd.yml

@@ -111,8 +111,10 @@ jobs:
           .venv\Scripts\Activate.ps1
           pip install --extra-index-url https://wheels.vtk.org .[ci]
 
+      # Use environment variable to keep the doctree and avoid redundant build for PDF pages
       - name: Create HTML documentation
         run: |
+          echo "SPHINXBUILD_KEEP_DOCTREEDIR=1" >> $GITHUB_ENV
           .venv\Scripts\Activate.ps1
           . .\doc\make.bat html
 
@@ -123,8 +125,11 @@ jobs:
           path: doc/_build/html
           retention-days: 7
 
+      # Use environment variable to remove the doctree after the build of PDF pages
+      # Keeping doctree could cause an issue, see https://github.com/ansys/pyaedt/pull/3844/files
       - name: Create PDF documentation
         run: |
+          echo "SPHINXBUILD_KEEP_DOCTREEDIR=0" >> $GITHUB_ENV
           .venv\Scripts\Activate.ps1
           . .\doc\make.bat pdf
 

doc/source/conf.py

@@ -74,10 +74,16 @@ def directory_size(directory_path):
 
 def remove_doctree(app, exception):
     """Remove the .doctree directory created during the documentation build."""
-    size = directory_size(app.doctreedir)
-    logger.info(f"Removing doctree {app.doctreedir} ({size} MB).")
-    shutil.rmtree(app.doctreedir, ignore_errors=True)
-    logger.info(f"Doctree removed.")
+
+    # Keep the doctree to avoid creating it twice. This is typically helpful in CI/CD
+    # where we want to build both HTML and PDF pages.
+    if bool(os.getenv("SPHINXBUILD_KEEP_DOCTREEDIR", False)):
+        logger.info(f"Keeping directory {app.doctreedir}.")
+    else:
+        size = directory_size(app.doctreedir)
+        logger.info(f"Removing doctree {app.doctreedir} ({size} MB).")
+        shutil.rmtree(app.doctreedir, ignore_errors=True)
+        logger.info(f"Doctree removed.")
 
 
 def copy_examples(app):
@@ -98,9 +104,9 @@ def copy_examples(app):
 def remove_examples(app, exception):
     """Remove the doc/source/examples directory created during the documentation build."""
     destination_dir = pathlib.Path(app.srcdir) / "examples"
+
     size = directory_size(destination_dir)
     logger.info(f"Removing directory {destination_dir} ({size} MB).")
-
     shutil.rmtree(destination_dir, ignore_errors=True)
     logger.info(f"Directory removed.")
 
@@ -283,7 +289,6 @@ def setup(app):
     "sphinx.ext.autodoc",
     "sphinx.ext.todo",
     "sphinx.ext.autosummary",
-    "sphinx.ext.intersphinx",
     "sphinx.ext.coverage",
     "sphinx_copybutton",
     "sphinx_design",
@@ -292,7 +297,6 @@ def setup(app):
     "recommonmark",
     "numpydoc",
     "ansys_sphinx_theme.extension.linkcode",
-    # "myst_parser"
 ]
 
 # MathJax config