CI: Add examples to nightly doc build (#4633)

.github/workflows/nightly-docs.yml

@@ -17,9 +17,11 @@ concurrency:
   cancel-in-progress: true
 
 jobs:
+
   doc-build:
-    name: Documentation build without examples
-    runs-on: ubuntu-latest
+    name: Documentation build with examples
+    runs-on: [ self-hosted, Windows, pyaedt ]
+    timeout-minutes: 720
     steps:
       - name: Install Git and checkout project
         uses: actions/checkout@v4
@@ -29,50 +31,68 @@ jobs:
         with:
           python-version: ${{ env.MAIN_PYTHON_VERSION }}
 
-      - name: Update pip
+      - name: Create virtual environment
         run: |
-          pip install --upgrade pip
+          python -m venv .venv
+          .venv\Scripts\Activate.ps1
+          python -m pip install pip -U
+          python -m pip install wheel setuptools -U
+          python -c "import sys; print(sys.executable)"
 
       - name: Install pyaedt and documentation dependencies
         run: |
-          pip install .[doc-no-examples]
+          .venv\Scripts\Activate.ps1
+          pip install .[doc]
 
       - name: Retrieve PyAEDT version
         id: version
         run: |
+          .venv\Scripts\Activate.ps1
           echo "PYAEDT_VERSION=$(python -c 'from pyaedt import __version__; print(__version__)')" >> $GITHUB_OUTPUT
           echo "PyAEDT version is: $(python -c "from pyaedt import __version__; print(__version__)")"
 
-      - name: Install doc build requirements
+      - name: Install CI dependencies (e.g. vtk-osmesa)
         run: |
-          sudo apt update
-          sudo apt install graphviz texlive-latex-extra latexmk texlive-xetex texlive-fonts-extra -y
+          .venv\Scripts\Activate.ps1
+          # Uninstall conflicting dependencies
+          pip uninstall --yes vtk
+          pip install --extra-index-url https://wheels.vtk.org vtk-osmesa==9.2.20230527.dev0
 
       # TODO: Update this step once pyaedt-examples is ready
-      - name: Build HTML documentation without examples
-        run: |
-          make -C doc clean
-          make -C doc html-no-examples
-
-      # Verify that sphinx generates no warnings
-      - name: Check for warnings
+      # NOTE: Use environment variable to keep the doctree and avoid redundant build for PDF pages
+      - name: Build HTML documentation with examples
+        env:
+          SPHINXBUILD_KEEP_DOCTREEDIR: "1"
         run: |
-          python doc/print_errors.py
-
-      - name: Build PDF documentation without examples
+          .venv\Scripts\Activate.ps1
+          .\doc\make.bat clean
+          .\doc\make.bat html
+
+      # TODO: Keeping this commented as reminder of https://github.com/ansys/pyaedt/issues/4296
+      # # Verify that sphinx generates no warnings
+      # - name: Check for warnings
+      #   run: |
+      #     .venv\Scripts\Activate.ps1
+      #     python doc/print_errors.py
+
+      # Use environment variable to remove the doctree after the build of PDF pages
+      - name: Build PDF documentation with examples
+        env:
+          SPHINXBUILD_KEEP_DOCTREEDIR: "0"
         run: |
-          make -C doc pdf-no-examples
+          .venv\Scripts\Activate.ps1
+          .\doc\make.bat pdf
 
       - name: Add assets to HTML docs
         run: |
           zip -r documentation-html.zip ./doc/_build/html
           mv documentation-html.zip ./doc/_build/html/_static/assets/download/
           cp doc/_build/latex/PyAEDT-Documentation-*.pdf ./doc/_build/html/_static/assets/download/pyaedt.pdf
 
-      - name: Upload HTML documentation without examples artifact
+      - name: Upload HTML documentation with examples artifact
         uses: actions/upload-artifact@v3
         with:
-          name: documentation-no-examples-html
+          name: documentation-html
           path: doc/_build/html
           retention-days: 7
 
@@ -83,6 +103,72 @@ jobs:
           path: doc/_build/latex/PyAEDT-Documentation-*.pdf
           retention-days: 7
 
+  # doc-build-without-examples:
+  #   name: Documentation build without examples
+  #   runs-on: ubuntu-latest
+  #   steps:
+  #     - name: Install Git and checkout project
+  #       uses: actions/checkout@v4
+
+  #     - name: Setup Python
+  #       uses: actions/setup-python@v5
+  #       with:
+  #         python-version: ${{ env.MAIN_PYTHON_VERSION }}
+
+  #     - name: Update pip
+  #       run: |
+  #         pip install --upgrade pip
+
+  #     - name: Install pyaedt and documentation dependencies
+  #       run: |
+  #         pip install .[doc-no-examples]
+
+  #     - name: Retrieve PyAEDT version
+  #       id: version
+  #       run: |
+  #         echo "PYAEDT_VERSION=$(python -c 'from pyaedt import __version__; print(__version__)')" >> $GITHUB_OUTPUT
+  #         echo "PyAEDT version is: $(python -c "from pyaedt import __version__; print(__version__)")"
+
+  #     - name: Install doc build requirements
+  #       run: |
+  #         sudo apt update
+  #         sudo apt install graphviz texlive-latex-extra latexmk texlive-xetex texlive-fonts-extra -y
+
+  #     # TODO: Update this step once pyaedt-examples is ready
+  #     - name: Build HTML documentation without examples
+  #       run: |
+  #         make -C doc clean
+  #         make -C doc html-no-examples
+
+  #     # Verify that sphinx generates no warnings
+  #     - name: Check for warnings
+  #       run: |
+  #         python doc/print_errors.py
+
+  #     - name: Build PDF documentation without examples
+  #       run: |
+  #         make -C doc pdf-no-examples
+
+  #     - name: Add assets to HTML docs
+  #       run: |
+  #         zip -r documentation-html.zip ./doc/_build/html
+  #         mv documentation-html.zip ./doc/_build/html/_static/assets/download/
+  #         cp doc/_build/latex/PyAEDT-Documentation-*.pdf ./doc/_build/html/_static/assets/download/pyaedt.pdf
+
+  #     - name: Upload HTML documentation without examples artifact
+  #       uses: actions/upload-artifact@v3
+  #       with:
+  #         name: documentation-no-examples-html
+  #         path: doc/_build/html
+  #         retention-days: 7
+
+  #     - name: Upload PDF documentation without examples artifact
+  #       uses: actions/upload-artifact@v3
+  #       with:
+  #         name: documentation-pdf
+  #         path: doc/_build/latex/PyAEDT-Documentation-*.pdf
+  #         retention-days: 7
+
   upload-dev-doc:
     name: Upload dev documentation
     runs-on: ubuntu-latest
@@ -93,7 +179,7 @@ jobs:
         with:
           cname: ${{ env.DOCUMENTATION_CNAME }}
           token: ${{ secrets.GITHUB_TOKEN }}
-          doc-artifact-name: 'documentation-no-examples-html'
+          doc-artifact-name: 'documentation-html'
 
   doc-index-dev:
     name: Deploy dev index docs