doc: basic gallery of examples (#226)

Author: jorgepiloto

.github/workflows/ci_cd_pr.yml

@@ -65,61 +65,92 @@ jobs:
 
   doc-build:
     name: "Doc build"
-    runs-on: ubuntu-latest
+    runs-on: [self-hosted, pystk]
     needs: doc-style
     timeout-minutes: 30
     steps:
 
+      - name: "Checkout the project"
+        uses: actions/checkout@v4
+
+      - name: "Generate the name of the Docker image and the container"
+        run: |
+          python_image_name=${{ env.STK_DOCKER_IMAGE }}-python${{ env.MAIN_PYTHON_VERSION }}
+          container_name=stk-python${{ env.MAIN_PYTHON_VERSION }}
+          echo "STK_PYTHON_IMAGE=$python_image_name" >> $GITHUB_ENV
+          echo "STK_CONTAINER=$container_name" >> $GITHUB_ENV
+
+      - name: "Start the container from the desired image"
+        run: |
+          docker run \
+            --detach -it \
+            --network="host" \
+            --name ${{ env.STK_CONTAINER }} \
+            --env ANSYSLMD_LICENSE_FILE=${{ env.LICENSE_SERVER_PORT }}@${{ secrets.LICENSE_SERVER }} \
+            --volume ${PWD}:/home/stk/pystk \
+            ${{ env.STK_PYTHON_IMAGE }}
+
+      - name: "Install Pandoc inside the container"
+        run: |
+          docker exec \
+            --user root \
+            --workdir ${{ env.PYSTK_DIR }} \
+            ${{ env.STK_CONTAINER }} /bin/bash -c \
+            "yum install -y epel-release && yum install -y pandoc --enablerepo=epel"
+
+      - name: "Install Tox"
+        run: |
+          docker exec \
+            --workdir ${{ env.PYSTK_DIR }} \
+            ${{ env.STK_CONTAINER }} /bin/bash -c \
+            "python -m pip install tox && rm -rf .tox"
+
       # Render the documentation including or excluding different sections
       # according to the labels of the pull-request.
 
       - name: "Build docs including the 'Examples' section"
         id: build-doc-with-examples
-        uses: ansys/actions/doc-build@v5
         if: |
           contains(github.event.pull_request.labels.*.name, 'docs:examples') &&
           !contains(github.event.pull_request.labels.*.name, 'docs:api')
-        with:
-          python-version: ${{ env.MAIN_PYTHON_VERSION }}
-        env:
-          BUILD_API: false
-          BUILD_EXAMPLES: true
+        run: |
+          docker exec \
+            --workdir ${{ env.PYSTK_DIR }} \
+            ${{ env.STK_CONTAINER }} /bin/bash -c \
+            "export BUILD_API=false BUILD_EXAMPLES=true && tox -e doc"
 
       - name: "Build docs including the 'API' section"
         id: build-doc-with-api
-        uses: ansys/actions/doc-build@v5
         if: |
           contains(github.event.pull_request.labels.*.name, 'docs:api') &&
           !contains(github.event.pull_request.labels.*.name, 'docs:examples')
-        with:
-          python-version: ${{ env.MAIN_PYTHON_VERSION }}
-        env:
-          BUILD_API: true
-          BUILD_EXAMPLES: false
+        run: |
+          docker exec \
+            --workdir ${{ env.PYSTK_DIR }} \
+            ${{ env.STK_CONTAINER }} /bin/bash -c \
+            "export BUILD_API=true BUILD_EXAMPLES=false && tox -e doc"
 
       - name: "Build docs excluding 'API' and 'Examples' sections"
         id: build-doc-minimum
-        uses: ansys/actions/doc-build@v5
         if: |
           !contains(github.event.pull_request.labels.*.name, 'docs:examples') &&
           !contains(github.event.pull_request.labels.*.name, 'docs:api')
-        with:
-          python-version: ${{ env.MAIN_PYTHON_VERSION }}
-        env:
-          BUILD_API: false
-          BUILD_EXAMPLES: false
+        run: |
+          docker exec \
+            --workdir ${{ env.PYSTK_DIR }} \
+            ${{ env.STK_CONTAINER }} /bin/bash -c \
+            "export BUILD_API=false BUILD_EXAMPLES=false && tox -e doc"
 
       - name: "Build docs including 'API' and 'Examples' sections"
         id: build-doc-full
-        uses: ansys/actions/doc-build@v5
         if: |
           contains(github.event.pull_request.labels.*.name, 'docs:examples') &&
           contains(github.event.pull_request.labels.*.name, 'docs:api')
-        with:
-          python-version: ${{ env.MAIN_PYTHON_VERSION }}
-        env:
-          BUILD_API: true
-          BUILD_EXAMPLES: true
+        run: |
+          docker exec \
+            --workdir ${{ env.PYSTK_DIR }} \
+            ${{ env.STK_CONTAINER }} /bin/bash -c \
+            "export BUILD_API=true BUILD_EXAMPLES=true && tox -e doc"
 
       # If required, combine partially rendered documentation with the nightly
       # build artifacts. Upload the generated documentation as an artifact in
@@ -134,15 +165,15 @@ jobs:
 
       - name: "Include 'API' section from nightly build docs"
         if: |
-          steps.build-doc-with-api.outcome == 'success' ||
+          steps.build-doc-with-examples.outcome == 'success' ||
           steps.build-doc-minimum.outcome == 'success'
         run: |
           cp -r gh-pages/version/dev/api doc/_build/html/api
           cp gh-pages/version/dev/index.html doc/_build/html/index.html
 
       - name: "Include 'Examples' section from nightly build docs"
         if: |
-          steps.build-doc-with-examples.outcome == 'success' ||
+          steps.build-doc-with-api.outcome == 'success' ||
           steps.build-doc-minimum.outcome == 'success'
         run: |
           cp gh-pages/version/dev/examples.html doc/_build/html/examples.html
@@ -155,6 +186,13 @@ jobs:
           path: doc/_build/html
           name: full-documentation-html
 
+      - name: "Stop the container"
+        if: always()
+        run: |
+          docker stop ${{ env.STK_CONTAINER }}
+          docker logs ${{ env.STK_CONTAINER }}
+          docker rm ${{ env.STK_CONTAINER }}
+
   tests:
     name: "Tests Python ${{ matrix.python }}"
     runs-on: [self-hosted, pystk]

.gitignore

@@ -164,3 +164,10 @@ distributions/
 
 # Backup files
 *.bak
+
+# Examples are kept at the root of the repository but copied at documentation
+# build time inside the documentation source directory
+doc/source/examples/
+
+# Ignore trash generated by Jupyter Notebook
+.Trash-1000/

.pre-commit-config.yaml

@@ -15,7 +15,7 @@ repos:
     # As per this issue https://github.com/pre-commit/pre-commit/issues/2936,
     # it looks like the `--all-files` only listens for the `exclude` option in a
     # pre-commit hook, ignoring `pyproject.toml` excludes.
-    exclude: ^(src/ansys/stk/core/internal/|tests/|doc/_build|doc/styles/)
+    exclude: ^(src/ansys/stk/core/internal/|tests/|doc/_build|doc/styles/|doc/source/_static)
     args: [--ignore-words=./doc/styles/Vocab/ANSYS/accept.txt]
     # TODO: pre-commit seems to ignore the configuration declared for codespell
     # in the `pyproject.toml` file. For more details, see `[tool.codespell]` in

doc/source/_static/css/highlight.css

@@ -0,0 +1,21 @@
+@import "../../ansys-sphinx-theme.css";
+
+/* Do not show number cells */
+.nbinput .prompt,
+.nboutput .prompt {
+    display: none;
+}
+
+/* Center output notebook images */
+.nboutput img {
+    display: block !important;
+    margin: 0 auto !important;
+}
+
+/* Remove the 'snapshot' label in the JupyterWidget snapshots */
+.nboutput img + * {
+    display: none;
+}
+
+/* Ensure that text in the code blocks has the desired font-size */
+.highlight { font-size: 1rem; background: #f0f0f0 !important; }