build_documentation.yml

name: Documentation Build

on: [pull_request, workflow_dispatch]

env:
  # Following env vars when changed will "reset" the mentioned cache,
  # by changing the cache file name. It is rendered as ...-v%RESET_XXX%-...
  # You should go up in number, if you go down (or repeat a previous value)
  # you might end up reusing a previous cache if it haven't been deleted already.
  # It applies 7 days retention policy by default.
  RESET_EXAMPLES_CACHE: 3
  RESET_DOC_BUILD_CACHE: 3
  RESET_AUTOSUMMARY_CACHE: 3


concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  docs-style:
    name: "Check documentation style"
    runs-on: ubuntu-latest
    steps:
      - name: "Check documentation style"
        uses: ansys/actions/doc-style@v5
        with:
          token: ${{ secrets.GITHUB_TOKEN }}
          vale-config: "doc/.vale.ini"
          vale-version: "2.29.6"

  docs_build:
    runs-on: ubuntu-latest

    steps:
      - uses: actions/checkout@v4

      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.10"

      - name: Update pip
        run: |
          pip install --upgrade pip

      - name: Install pyaedt
        run: |
          pip install .[doc]

      - name: Verify pyaedt can be imported
        run: python -c "import pyaedt"

      - 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: Cache docs build directory
      #   uses: actions/cache@v3
      #   with:
      #     path: doc/build
      #     key: doc-build-v${{ env.RESET_DOC_BUILD_CACHE }}-${{ steps.version.outputs.PYAEDT_VERSION }}-${{ github.sha }}
      #     restore-keys: |
      #       doc-build-v${{ env.RESET_DOC_BUILD_CACHE }}-${{ steps.version.outputs.PYAEDT_VERSION }}
      # - name: Cache autosummary
      #   uses: actions/cache@v3
      #   with:
      #     path: doc/source/**/_autosummary/*.rst
      #     key: autosummary-v${{ env.RESET_AUTOSUMMARY_CACHE }}-${{ steps.version.outputs.PYAEDT_VERSION }}-${{ github.sha }}
      #     restore-keys: |
      #       autosummary-v${{ env.RESET_AUTOSUMMARY_CACHE }}-${{ steps.version.outputs.PYAEDT_VERSION }}

      - name: Install doc build requirements
        run: |
          sudo apt update
          sudo apt install graphviz texlive-latex-extra latexmk texlive-xetex texlive-fonts-extra -y

      # run doc build, without creating the examples directory
      # note that we have to add the examples file here since it won't
      # be created as gallery is disabled on linux.
      - name: Documentation Build (HTML)
        run: |
          make -C doc clean
          mkdir doc/source/examples -p
          echo $'Examples\n========' > doc/source/examples/index.rst
          make -C doc phtml-no-examples SPHINXOPTS="-j auto -w build_errors.txt -N"

      # Verify that sphinx generates no warnings
      - name: Check for warnings
        run: |
          python doc/print_errors.py

      - name: Upload Documentation
        uses: actions/upload-artifact@v3
        with:
          name: Documentation
          path: doc/_build/html
          retention-days: 7

      - name: Documentation Build (PDF)
        run: |
          make -C doc pdf-no-examples

      - name: Upload documentation PDF artifact
        uses: actions/upload-artifact@v3
        with:
          name: Documentation-pdf
          path: doc/_build/latex/*.pdf
          retention-days: 7