docs.yml

name: docs

on:
# Can be called by the CI
  workflow_call:
    inputs:
      python_version:
        required: false
        type: string
        default: "3.10"
      ANSYS_VERSION:
        required: false
        type: string
        default: "251"
      standalone_suffix:
        description: "Suffix of the branch on standalone"
        required: false
        type: string
        default: ''
      event_name:
        description: "Name of event calling"
        required: true
        type: string
        default: ''
      generate_pdf:
        description: "Whether to build the PDF doc"
        type: string
        default: 'True'
      debug:
        description: "Debug verbose mode"
        type: string
        default: 'True'
# Can be called manually
  workflow_dispatch:
    inputs:
      python_version:
        description: "Python interpreter"
        required: true
        type: string
        default: "3.10"
      ANSYS_VERSION:
        description: "ANSYS version"
        required: true
        type: string
        default: "251"
      standalone_suffix:
        description: "Suffix of the branch on standalone"
        required: false
        type: string
        default: ''
      generate_pdf:
        description: "Whether to build the PDF doc"
        type: string
        default: 'True'

env:
  PACKAGE_NAME: ansys-dpf-post
  MODULE: post

jobs:
  doc-style:
    name: "Check doc style"
    runs-on: ubuntu-latest
    steps:
        - name: "Running documentation style checks"
          uses: ansys/actions/doc-style@v8
          with:
            token: ${{ secrets.GITHUB_TOKEN }}

  docs:
    name: "Documentation"
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: "Set licensing if necessary"
        if: inputs.ANSYS_VERSION > 231
        shell: bash
        run: |
          echo "ANSYS_DPF_ACCEPT_LA=Y" >> $GITHUB_ENV
          echo "ANSYSLMD_LICENSE_FILE=1055@${{ secrets.LICENSE_SERVER }}" >> $GITHUB_ENV

      - name: Setup Python
        uses: actions/setup-python@v5.3.0
        with:
          python-version: ${{ inputs.python_version }}

      - name: "Install OS packages"
        shell: bash
        run: |
          sudo apt update
          sudo apt install pandoc texlive-latex-extra latexmk

      - name: "Build Package"
        id: build-package
        uses: ansys/pydpf-actions/build_package@v2.3
        with:
          python-version: ${{ inputs.python_version }}
          ANSYS_VERSION: ${{inputs.ANSYS_VERSION}}
          PACKAGE_NAME: ${{env.PACKAGE_NAME}}
          MODULE: ${{env.MODULE}}
          dpf-standalone-TOKEN: ${{secrets.DPF_PIPELINE}}
          install_extras: plotting
          wheel: false
          wheelhouse: false
          standalone_suffix: ${{ inputs.standalone_suffix }}

      - name: "Setup headless display"
        uses: pyvista/setup-headless-display-action@v2

      - name: "Install documentation requirements"
        shell: bash
        run: |
          pip install -r requirements/requirements_docs.txt

      - name: "List installed packages"
        shell: bash
        run: pip list

      - name: "Build sphinx doc"
        shell: bash
        run: |
          export SPHINX_APIDOC_OPTIONS=inherited-members
          sphinx-apidoc -o doc/source/api src/ansys ${{inputs.build_extras}} -f --implicit-namespaces --separate --no-headings $DEBUG_SPHINX

      - name: "Build HTML Documentation"
        shell: bash
        working-directory: doc
        run: |
          export TEMP=${{ runner.temp }}
          make clean
          echo "Making html doc..."
          make html $DEBUG_HTML >> log.txt 2>&1

      - name: "Check for success"
        shell: bash
        working-directory: doc
        run: |
          case `tail -n 5 log.txt | grep -F "build succeeded" >/dev/null; echo $?` in
          0)
            echo "Build succeeded!"
            exit 0;;
          1)
            echo "Documentation generation failed, please check previous step!"
            exit 1;;
          *)
            echo "An error occurred while checking success of the previous step!"
            exit 1;;
          esac

      - name: "Build PDF Documentation"
        shell: bash
        working-directory: doc
        if: ${{ inputs.generate_pdf == 'true' }}
        run: |
          export TEMP=${{ runner.temp }}
          echo "Making pdf doc..."
          make pdf $DEBUG_PDF

      - name: "Upload Documentation Build log"
        uses: actions/upload-artifact@v4
        with:
          name: doc-${{env.PACKAGE_NAME}}-log
          path: doc/*.txt
        if: always()

      - name: "Zip HTML Documentation"
        uses: vimtor/action-zip@v1.2
        with:
          files: doc/build/html/
          dest: HTML-doc-${{env.PACKAGE_NAME}}.zip
        if: always()

      - name: "Upload HTML Documentation"
        uses: actions/upload-artifact@v4
        with:
          name: HTML-doc-${{env.PACKAGE_NAME}}.zip
          path: HTML-doc-${{env.PACKAGE_NAME}}.zip
        if: always()

      - name: "Find PDF Documentation"
        shell: bash
        if: ${{ inputs.generate_pdf == 'true' }}
        id: pdf
        working-directory: doc/build/latex
        run: |
          pattern="PyDPF-*.pdf"
          files=( $pattern )
          echo "PDF_file=${files[0]}" >> $GITHUB_OUTPUT
          echo "Found PDF doc: ${files[0]}"

      - name: "Zip PDF Documentation"
        uses: vimtor/action-zip@v1.2
        if: ${{ inputs.generate_pdf == 'true' }}
        with:
          files: doc/build/latex/${{ steps.pdf.outputs.PDF_file }}
          dest: PDF-doc-${{env.PACKAGE_NAME}}.zip

      - name: "Upload PDF Documentation"
        uses: actions/upload-artifact@v4
        if: inputs.generate_pdf == 'true'
        with:
          name: PDF-doc-${{env.PACKAGE_NAME}}
          path: PDF-doc-${{env.PACKAGE_NAME}}.zip

      - name: "Kill all servers"
        uses: ansys/pydpf-actions/kill-dpf-servers@v2.3
        if: always()