feat: extend doc-build to be windows compatible

_doc-build-linux/action.yml

@@ -0,0 +1,257 @@
+# Copyright (C) 2022 - 2024 ANSYS, Inc. and/or its affiliates.
+# SPDX-License-Identifier: MIT
+#
+#
+# Permission is hereby granted, free of charge, to any person obtaining a copy
+# of this software and associated documentation files (the "Software"), to deal
+# in the Software without restriction, including without limitation the rights
+# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+# copies of the Software, and to permit persons to whom the Software is
+# furnished to do so, subject to the following conditions:
+#
+# The above copyright notice and this permission notice shall be included in all
+# copies or substantial portions of the Software.
+#
+# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+# SOFTWARE.
+
+name: >
+  Documentation build action
+
+description: |
+  Build library documentation using `Sphinx
+  <https://www.sphinx-doc.org/en/master/>`_. The action installs documentation
+  dependencies provided either in a requirement file, e.g.
+  ``requirements/requirements_doc.txt``, or in the ``[doc]`` section of the
+  additional dependencies in the ``pyproject.toml`` file. Assuming that
+  `sphinx-build
+  <https://www.sphinx-doc.org/en/master/man/sphinx-build.html>`_ is available
+  after installing the documentation dependencies, the action uses it
+  to generate documentation from the source. It requires that all the
+  documentation is contained in the ``doc/`` directory of a project. The
+  action locates the ``doc/Makefile`` and runs the ``make html`` and
+  ``make pdf`` commands. If desired, the ``make json`` command can
+  also be executed to generate JSON documentation.
+
+inputs:
+
+  # Required inputs
+
+  python-version:
+    description: >
+        Python version used for installing and running ``Sphinx``.
+    required: true
+    type: string
+
+  use-python-cache:
+    description: >
+      Whether to use the Python cache for installing previously downloaded
+      libraries. If ``true``, previously downloaded libraries are installed from the
+      Python cache. If ``false``, libraries are downloaded from the PyPI index.
+    required: true
+    type: boolean
+
+  sphinxopts:
+    description: |
+      Set of options to pass to the ``Sphinx`` builder.
+
+      .. note::
+
+          This will override the ``SPHINXOPTS`` declared in your Makefile.
+
+    required: true
+    type: string
+
+  dependencies:
+    description: >
+      String of system dependencies to be installed before building the
+      documentation of the project.
+    required: true
+    type: string
+
+  skip-dependencies-cache:
+    description: >
+      Whether to ignore dependencies cache or not - for OS libraries.
+    required: true
+    type: boolean
+
+  requires-xvfb:
+    description: |
+      Whether to install `X Virtual Frame Buffer (XVFB)
+      <https://www.x.org/releases/X11R7.6/doc/man/man1/Xvfb.1.xhtml>`_ and run
+      the whole test session using XVFB.
+    required: true
+    type: boolean
+
+  skip-install:
+    description: >
+      Whether to skip the installation of the project.
+      Pure documentation projects require that this action be set to ``false``
+      because there is no Python library associated with the project.
+    required: true
+    type: boolean
+
+  requirements-file:
+    description: >
+      Path to the requirements file in case it needs to be in a specific location.
+      This is useful for non python projects, where you don't necessarily have a requirements
+      file in the root of the project.
+    required: true
+    type: string
+
+  checkout:
+    description: >
+      Whether to clone the repository in the CI/CD machine.
+    required: true
+    type: boolean
+
+  skip-json-build:
+    description: >
+      Whether to skip the generation of JSON documentation.
+    required: true
+    type: boolean
+
+  check-links:
+    description: >
+      Whether to perform external link checks during the generation of
+      documentation.
+    required: true
+    type: boolean
+
+runs:
+  using: "composite"
+  steps:
+
+    - name: "Collect system dependencies"
+      shell: bash
+      run: |
+        if [[ ${{ inputs.requires-xvfb }} == 'true' ]]; then
+          echo "NEEDED_DEPS=$(echo '${{ inputs.dependencies }} xvfb')" >> $GITHUB_ENV
+        else
+          echo "NEEDED_DEPS=$(echo '${{ inputs.dependencies }}')" >> $GITHUB_ENV
+        fi
+
+    - name: "Cache apt packages needed"
+      uses: awalsh128/cache-apt-pkgs-action@v1.3.1
+      if: inputs.skip-dependencies-cache == 'false' && env.NEEDED_DEPS != ''
+      with:
+        packages: ${{ env.NEEDED_DEPS }}
+        version: 1.0
+
+    - name: "Update apt-get"
+      shell: bash
+      run: |
+        sudo apt-get update
+
+    - name: "Install system dependencies"
+      shell: bash
+      run: |
+        sudo apt-get install -y ${{ env.NEEDED_DEPS }}
+
+    - name: "Install LaTeX"
+      shell: bash
+      run: |
+        sudo apt-get install -y texlive-latex-extra latexmk
+
+    - name: "Check if requirements.txt file exists"
+      shell: bash
+      run: |
+        echo "EXISTS_DOC_REQUIREMENTS=$(if [ -f ${{ inputs.requirements-file }} ]; then echo 'true'; else echo 'false'; fi)" >> $GITHUB_ENV
+
+    - name: "Print previous output"
+      shell: bash
+      run: |
+        echo "Output was found ${{ env.EXISTS_DOC_REQUIREMENTS }}"
+
+    - name: "Update pip"
+      shell: bash
+      run: python -m pip install -U pip
+
+    - name: "Install documentation dependencies from requirements file"
+      shell: bash
+      if: env.EXISTS_DOC_REQUIREMENTS == 'true'
+      run: |
+        python -m pip install -r ${{ inputs.requirements-file }}
+
+    - name: "Install Python library"
+      shell: bash
+      if: inputs.skip-install == 'false'
+      run: |
+        python -m pip install .
+
+    - name: "Install documentation dependencies from pyproject.toml"
+      shell: bash
+      if: env.EXISTS_DOC_REQUIREMENTS == 'false'
+      run: |
+        if grep -q 'build-backend = "poetry\.core\.masonry\.api"' "pyproject.toml"; then
+          python -m pip install poetry
+          poetry install --with doc
+        else
+          python -m pip install .[doc]
+        fi
+
+    - name: "Determine make command context"
+      shell: bash
+      run: |
+        if grep -q 'build-backend = "poetry\.core\.masonry\.api"' "pyproject.toml"; then
+          echo "SPHINX_BUILD_MAKE=$(echo 'poetry run -- make')" >> $GITHUB_ENV
+        else
+          echo "SPHINX_BUILD_MAKE=$(echo 'make')" >> $GITHUB_ENV
+        fi
+
+    - name: "Build HTML, PDF, and JSON documentation"
+      if: inputs.requires-xvfb == 'false'
+      shell: bash
+      run: |
+        if [[ ${{ inputs.check-links }} == 'true' ]];
+        then
+          ${{ env.SPHINX_BUILD_MAKE }} -C doc linkcheck SPHINXOPTS="${{ inputs.sphinxopts }}"
+        fi
+        ${{ env.SPHINX_BUILD_MAKE }} -C doc html SPHINXOPTS="${{ inputs.sphinxopts }}"
+        ${{ env.SPHINX_BUILD_MAKE }} -C doc pdf
+        if [[ ${{ inputs.skip-json-build }} == 'false' ]];
+        then
+          ${{ env.SPHINX_BUILD_MAKE }} -C doc json SPHINXOPTS="${{ inputs.sphinxopts }}"
+        fi
+
+    - name: "Build HTML, PDF, and JSON documentation using xvfb"
+      if: inputs.requires-xvfb == 'true'
+      shell: bash
+      run: |
+        if [[ ${{ inputs.check-links }} == 'true' ]];
+        then
+          xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc linkcheck SPHINXOPTS="${{ inputs.sphinxopts }}"
+        fi
+        xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc html SPHINXOPTS="${{ inputs.sphinxopts }}"
+        xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc pdf
+        if [[ ${{ inputs.skip-json-build }} == 'false' ]];
+        then
+          xvfb-run ${{ env.SPHINX_BUILD_MAKE }} -C doc json SPHINXOPTS="${{ inputs.sphinxopts }}"
+        fi
+
+    - name: "Upload HTML documentation artifact"
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentation-html
+        path: doc/_build/html
+        retention-days: 7
+
+    - name: "Upload PDF documentation artifact"
+      uses: actions/upload-artifact@v4
+      with:
+        name: documentation-pdf
+        path: doc/_build/latex/*.pdf
+        retention-days: 7
+
+    - name: "Upload JSON documentation artifact"
+      uses: actions/upload-artifact@v4
+      if: inputs.skip-json-build == 'false'
+      with:
+        name: documentation-json
+        path: doc/_build/json
+        retention-days: 7