From ee332e05c09fc72eca08fe402cb8cf5e00fed8c9 Mon Sep 17 00:00:00 2001
From: SMoraisAnsys <146729917+SMoraisAnsys@users.noreply.github.com>
Date: Mon, 26 Feb 2024 09:34:21 +0000
Subject: [PATCH] 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 |  5 +++++
 doc/source/conf.py          | 18 +++++++++++-------
 2 files changed, 16 insertions(+), 7 deletions(-)

diff --git a/.github/workflows/ci_cd.yml b/.github/workflows/ci_cd.yml
index 7565fb237..117a1bba8 100644
--- a/.github/workflows/ci_cd.yml
+++ b/.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
 
diff --git a/doc/source/conf.py b/doc/source/conf.py
index 778796dd7..61c00f25c 100644
--- a/doc/source/conf.py
+++ b/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