ci_tests.yml

name: CI - Tests

on:
  workflow_call:
    inputs:
      # General
      runner:
        description: "The runner to use for the workflow. Note, the callable workflow expects a Linux/Unix system."
        required: false
        type: string
        default: ubuntu-latest
      install_extras:
        description: "Any extras to install from the local repository through 'pip'. Must be encapsulated in square parentheses (`[]`) and be separated by commas (`,`) without any spaces. Example: `'[dev,pre-commit]'`."
        required: false
        type: string
        default: ""
      system_dependencies:
        description: "A single (space-separated) or multi-line string of Ubuntu APT packages to install prior to installing the local repository."
        required: false
        type: string
        default: ""

      # pre-commit
      run_pre-commit:
        description: "Run the `pre-commit` test job."
        required: false
        type: boolean
        default: true
      python_version_pre-commit:
        description: "The Python version to use for the `pre-commit` test job."
        required: false
        type: string
        default: "3.9"
      pip_index_url_pre-commit:
        description: "A URL to a PyPI repository index. Defaults to 'https://pypi.org/simple/'."
        required: false
        type: string
        default: "https://pypi.org/simple/"
      pip_extra_index_urls_pre-commit:
        description: "A space-delimited string of URLs to additional PyPI repository indices."
        required: false
        type: string
        default: ""
      skip_pre-commit_hooks:
        description: "A comma-separated list of pre-commit hook IDs to skip when running `pre-commit` after updating hooks."
        required: false
        type: string
        default: ""

      # pylint & safety
      python_version_pylint_safety:
        description: "The Python version to use for the `pylint` and `safety` test jobs."
        required: false
        type: string
        default: "3.9"
      pip_index_url_pylint_safety:
        description: "A URL to a PyPI repository index. Defaults to 'https://pypi.org/simple/'."
        required: false
        type: string
        default: "https://pypi.org/simple/"
      pip_extra_index_urls_pylint_safety:
        description: "A space-delimited string of URLs to additional PyPI repository indices."
        required: false
        type: string
        default: ""

      run_pylint:
        description: "Run the `pylint` test job."
        required: false
        type: boolean
        default: false
      pylint_options:
        description: "Single (space-separated) or multi-line string of pylint command line options. Note, this is only valid if 'pylint_runs' is not defined."
        required: false
        type: string
        default: ""
      pylint_targets:
        description: "Space-separated string of pylint file and folder targets. Note, this is only valid if 'pylint_runs' is not defined."
        required: false
        type: string
        default: ""
      pylint_runs:
        description: "Multi-line string with each line representing a separate pylint run/execution. This should include all desired options and targets. Important, the inputs 'pylint_options' and 'pylint_targets' will be ignored if this is defined."
        required: false
        type: string
        default: ""

      run_safety:
        description: "Run the `safety` test job."
        required: false
        type: boolean
        default: false
      safety_options:
        description: "Single (space-separated) or multi-line string of safety command line options."
        required: false
        type: string
        default: ""

      # Build package / distribution
      run_build_package:
        description: "Run the 'build package' test job."
        required: false
        type: boolean
        default: true
      python_version_package:
        description: "The Python version to use for the `build package` test job."
        required: false
        type: string
        default: "3.9"
      pip_index_url_package:
        description: "A URL to a PyPI repository index. Defaults to 'https://pypi.org/simple/'."
        required: false
        type: string
        default: "https://pypi.org/simple/"
      pip_extra_index_urls_package:
        description: "A space-delimited string of URLs to additional PyPI repository indices."
        required: false
        type: string
        default: ""
      build_libs:
        description: "A space-separated list of packages to install via PyPI (`pip install`)."
        required: false
        type: string
        default: ""
      build_cmd:
        description: "The package build command, e.g., `'flit build'` or `'python -m build'` (default)."
        required: false
        type: string
        default: "python -m build"

      # Build documentation
      run_build_docs:
        description: "Run the 'build documentation' test job."
        required: false
        type: boolean
        default: true
      python_version_docs:
        description: "The Python version to use for the `build documentation` test job."
        required: false
        type: string
        default: "3.9"
      pip_index_url_docs:
        description: "A URL to a PyPI repository index. Defaults to 'https://pypi.org/simple/'."
        required: false
        type: string
        default: "https://pypi.org/simple/"
      pip_extra_index_urls_docs:
        description: "A space-delimited string of URLs to additional PyPI repository indices."
        required: false
        type: string
        default: ""
      relative:
        description: "Whether or not to use the locally installed Python package(s), and install it as an editable, _only_ when running the `build_docs` job."
        required: false
        type: boolean
        default: false
      warnings_as_errors:
        description: "Build the documentation in 'strict' mode, treating warnings as errors. **Important**: If this is set to `false`, beware that the documentation may _not_ be rendered or built as one may have intended. Default: `true`."
        required: false
        type: boolean
        default: true

      # MkDocs
      use_mkdocs:
        description: "Whether or not to build the documentation using the MkDocs framework. Mutually exclusive with `use_sphinx`."
        required: false
        type: boolean
        default: false
      update_python_api_ref:
        description: "Whether or not to update the Python API documentation reference. **Note**: If this is 'true', 'package_dirs' is _required_."
        required: false
        type: boolean
        default: true
      package_dirs:
        description: "A multi-line string of paths to Python package directories relative to the repository directory to be considered for creating the Python API reference documentation. Example: `'src/my_package'`. **Important**: This is _required_ if 'run_build_docs' and 'update_python_api_ref' are 'true'."
        required: false
        type: string
        default: ""
      update_docs_landing_page:
        description: "Whether or not to update the documentation landing page. The landing page will be based on the root README.md file."
        required: false
        type: boolean
        default: true
      exclude_dirs:
        description: "A multi-line string of directories to exclude in the Python API reference documentation. Note, only directory names, not paths, may be included. Note, all folders and their contents with these names will be excluded. Defaults to `'__pycache__'`. Important: When a user value is set, the preset value is overwritten - hence `'__pycache__'` should be included in the user value if one wants to exclude these directories."
        required: false
        type: string
        default: "__pycache__"
      exclude_files:
        description: "A multi-line string of files to exclude in the Python API reference documentation. Note, only full file names, not paths, may be included, i.e., filename + file extension. Note, all files with these names will be excluded. Defaults to `'__init__.py'`. Important: When a user value is set, the preset value is overwritten - hence `'__init__.py'` should be included in the user value if one wants to exclude these files."
        required: false
        type: string
        default: "__init__.py"
      full_docs_dirs:
        description: "A multi-line string of directories in which to include everything - even those without documentation strings. This may be useful for a module full of data models or to ensure all class attributes are listed."
        required: false
        type: string
        default: ""
      full_docs_files:
        description: "A multi-line string of relative paths to files in which to include everything - even those without documentation strings. This may be useful for a file full of data models or to ensure all class attributes are listed."
        required: false
        type: string
        default: ""
      special_file_api_ref_options:
        description: "A multi-line string of combinations of a relative path to a Python file and a fully formed mkdocstrings option that should be added to the generated MarkDown file for the Python API reference documentation. Example: 'my_module/py_file.py,show_bases:false'. Encapsulate the value in double quotation marks (\") if including spaces ( ). Important: If multiple `package_dirs` are supplied, the relative path MUST include/start with the appropriate 'package_dir' value, e.g., '\"my_package/my_module/py_file.py,show_bases: false\"'."
        required: false
        type: string
        default: ""
      landing_page_replacements:
        description: "A multi-line string of replacements (mappings) to be performed on README.md when creating the documentation's landing page (index.md). This list ALWAYS includes replacing `'docs/'` with an empty string to correct relative links, i.e., this cannot be overwritten. By default `'(LICENSE)'` is replaced by `'(LICENSE.md)'`."
        required: false
        type: string
        default: "(LICENSE),(LICENSE.md)"
      landing_page_replacement_separator:
        description: "String to separate a replacement's 'old' to 'new' parts. Defaults to a comma (`,`)."
        required: false
        type: string
        default: ","
      debug:
        description: "Whether to do print extra debug statements."
        required: false
        type: boolean
        default: false

      # Sphinx
      use_sphinx:
        description: "Whether or not to build the documentation using the Sphinx framework. Mutually exclusive with `use_mkdocs`."
        required: false
        type: boolean
        default: false
      sphinx-build_options:
        description: "Single (space-separated) or multi-line string of command-line options to use when calling `sphinx-build`. Note, the `-W` option will be added if 'warnings_as_errors' is 'true' (default)."
        required: false
        type: string
        default: ""
      docs_folder:
        description: "The path to the root documentation folder relative to the repository root. Defaults to 'docs'."
        required: false
        type: string
        default: "docs"
      build_target_folder:
        description: "The path to the target folder for the documentation build relative to the repository root. Defaults to 'site'."
        required: false
        type: string
        default: "site"

jobs:
  pre-commit:
    name: Run `pre-commit`
    if: inputs.run_pre-commit
    runs-on: ${{ inputs.runner }}

    steps:
    - name: Checkout ${{ github.repository }}
      uses: actions/checkout@v6

    - name: Set up Python ${{ inputs.python_version_pre-commit }}
      uses: actions/setup-python@v6
      with:
        python-version: "${{ inputs.python_version_pre-commit }}"
        allow-prereleases: true

    - name: Install system dependencies
      if: inputs.system_dependencies != ''
      run: |
        if [[ "${{ inputs.system_dependencies }}" =~ \n ]]; then
          # Expected to be a multi-line string
          SYSTEM_PACKAGES=()
          while IFS= read -r line; do
            if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi
          done <<< "${{ inputs.system_dependencies }}"
        else
          # Expected to be a single-line string
          SYSTEM_PACKAGES=(${{ inputs.system_dependencies }})
        fi

        sudo apt update && sudo apt install -y "${SYSTEM_PACKAGES[@]}"

    - name: Install Python dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -U setuptools wheel
        pip install .${{ inputs.install_extras }}
      env:
        PIP_INDEX_URL: ${{ inputs.pip_index_url_pre-commit }}
        PIP_EXTRA_INDEX_URL: ${{ inputs.pip_extra_index_urls_pre-commit }}

    - name: Test with `pre-commit`
      run: SKIP=${{ inputs.skip_pre-commit_hooks }} pre-commit run --all-files

  pylint_and_safety:
    name: Run `pylint` & `safety`
    if: inputs.run_pylint || inputs.run_safety
    runs-on: ${{ inputs.runner }}

    steps:
    - name: This job is deprecated
      run: |
        echo "This job is deprecated. See https://sintef.github.io/ci-cd/latest/workflows/ci_tests/#run-pylint-safety"
        echo "::warning file=ci_tests.yml,line=299,col=9::The 'Run `pylint` & `safety`' job is deprecated. See https://sintef.github.io/ci-cd/latest/workflows/ci_tests/#run-pylint-safety"

    - name: Checkout ${{ github.repository }}
      uses: actions/checkout@v6
      with:
        fetch-depth: 2

    - name: Set up Python ${{ inputs.python_version_pylint_safety }}
      uses: actions/setup-python@v6
      with:
        python-version: "${{ inputs.python_version_pylint_safety }}"
        allow-prereleases: true

    - name: Install system dependencies
      if: inputs.system_dependencies != ''
      run: |
        if [[ "${{ inputs.system_dependencies }}" =~ \n ]]; then
          # Expected to be a multi-line string
          SYSTEM_PACKAGES=()
          while IFS= read -r line; do
            if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi
          done <<< "${{ inputs.system_dependencies }}"
        else
          # Expected to be a single-line string
          SYSTEM_PACKAGES=(${{ inputs.system_dependencies }})
        fi

        sudo apt update && sudo apt install -y "${SYSTEM_PACKAGES[@]}"

    - name: Install dependencies
      run: |
        python -m pip install -U pip
        pip install -U setuptools wheel
        pip install .${{ inputs.install_extras }}
        if [ "${{ inputs.run_pylint }}" == "true" ]; then
          pip install pylint
        fi
        if [ "${{ inputs.run_safety }}" == "true" ]; then
          pip install safety
        fi
      env:
        PIP_INDEX_URL: ${{ inputs.pip_index_url_pylint_safety }}
        PIP_EXTRA_INDEX_URL: ${{ inputs.pip_extra_index_urls_pylint_safety }}

    - name: Run `pylint`
      if: inputs.run_pylint
      run: |
        if [ -n "${{ inputs.pylint_runs }}" ]; then
          while IFS= read -r line; do
            if [ -n "${line}" ]; then pylint ${line}; fi
          done <<< "${{ inputs.pylint_runs }}"
        else
          if [ -z "${{ inputs.pylint_targets }}" ]; then
            echo "Please supply the 'pylint_targets' input, since you are not using the 'pylint_runs' input."
          fi

          if [[ "${{ inputs.pylint_options }}" =~ \n ]]; then
            # Expected to be a multi-line string
            PYLINT_OPTIONS=()
            while IFS= read -r line; do
              if [ -n "${line}" ]; then PYLINT_OPTIONS+=("${line}"); fi
            done <<< "${{ inputs.pylint_options }}"
          else
            # Expected to be a single-line string
            PYLINT_OPTIONS=(${{ inputs.pylint_options }})
          fi

          pylint "${PYLINT_OPTIONS[@]}" ${{ inputs.pylint_targets }}
        fi

    - name: Run `safety`
      if: inputs.run_safety
      run: |
        if [[ "${{ inputs.safety_options }}" =~ \n ]]; then
          # Expected to be a multi-line string
          SAFETY_OPTIONS=()
          while IFS= read -r line; do
            if [ -n "${line}" ]; then SAFETY_OPTIONS+=("${line}"); fi
          done <<< "${{ inputs.safety_options }}"
        else
          # Expected to be a single-line string
          SAFETY_OPTIONS=(${{ inputs.safety_options }})
        fi

        pip freeze | safety check --stdin "${SAFETY_OPTIONS[@]}"

  build-package:
    name: Build distribution package
    if: inputs.run_build_package
    runs-on: ${{ inputs.runner }}

    steps:
    - name: Checkout ${{ github.repository }}
      uses: actions/checkout@v6

    - name: Set up Python ${{ inputs.python_version_package }}
      uses: actions/setup-python@v6
      with:
        python-version: "${{ inputs.python_version_package }}"
        allow-prereleases: true

    - name: Install system dependencies
      if: inputs.system_dependencies != ''
      run: |
        if [[ "${{ inputs.system_dependencies }}" =~ \n ]]; then
          # Expected to be a multi-line string
          SYSTEM_PACKAGES=()
          while IFS= read -r line; do
            if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi
          done <<< "${{ inputs.system_dependencies }}"
        else
          # Expected to be a single-line string
          SYSTEM_PACKAGES=(${{ inputs.system_dependencies }})
        fi

        sudo apt update && sudo apt install -y "${SYSTEM_PACKAGES[@]}"

    - name: Install Python dependencies
      run: |
        python -m pip install -U pip
        pip install -U setuptools wheel build
        if [ -n "${{ inputs.build_libs }}" ]; then
          pip install ${{ inputs.build_libs }}
        fi
      env:
        PIP_INDEX_URL: ${{ inputs.pip_index_url_package }}
        PIP_EXTRA_INDEX_URL: ${{ inputs.pip_extra_index_urls_package }}

    - name: Check building distribution
      run: ${{ inputs.build_cmd }}

  docs:
    name: Build Documentation
    if: inputs.run_build_docs
    runs-on: ${{ inputs.runner }}

    steps:
    - name: Determine framework
      id: determine_framework
      run: |
        if [[ \
          ("${{ inputs.use_mkdocs }}" == "false" && "${{ inputs.use_sphinx }}" == "false") || \
          ("${{ inputs.use_mkdocs }}" == "true" && "${{ inputs.use_sphinx }}" == "false") ]]; then
          # (Default to) using MkDocs
          echo "Framework determined: MkDocs"
          echo "framework=mkdocs" >> $GITHUB_OUTPUT
        elif [[ "${{ inputs.use_mkdocs }}" == "false" && "${{ inputs.use_sphinx }}" == "true" ]]; then
          # Use Sphinx
          echo "Framework determined: Sphinx"
          echo "framework=sphinx" >> $GITHUB_OUTPUT
        else
          echo "Could not determine what documentation framework to use."
          echo "Note, the inputs 'use_mkdocs' and 'use_sphinx' are mutually exclusive."
          echo "The found values:"
          echo "  use_mkdocs=${{ inputs.use_mkdocs }}"
          echo "  use_sphinx=${{ inputs.use_sphinx }}"
          exit 1
        fi

    - name: Validate inputs
      run: |
        if [[ "${{ steps.determine_framework.outputs.framework }}" == "mkdocs" && ! "${{ inputs.python_version_docs }}" =~ ^3\.([8-9]|1[0-4])(\..*)?$ ]]; then
          echo "Python version '${{ inputs.python_version_docs }}' is not supported."
          echo "Supported versions are: 3.8, 3.9, 3.10, 3.11, 3.12, 3.13, 3.14."
          exit 1
        fi

    - name: Checkout ${{ github.repository }}
      uses: actions/checkout@v6
      with:
        fetch-depth: 2

    - name: Set up Python ${{ inputs.python_version_docs }}
      uses: actions/setup-python@v6
      with:
        python-version: "${{ inputs.python_version_docs }}"
        allow-prereleases: true

    - name: Install system dependencies
      if: inputs.system_dependencies != ''
      run: |
        if [[ "${{ inputs.system_dependencies }}" =~ \n ]]; then
          # Expected to be a multi-line string
          SYSTEM_PACKAGES=()
          while IFS= read -r line; do
            if [ -n "${line}" ]; then SYSTEM_PACKAGES+=("${line}"); fi
          done <<< "${{ inputs.system_dependencies }}"
        else
          # Expected to be a single-line string
          SYSTEM_PACKAGES=(${{ inputs.system_dependencies }})
        fi

        sudo apt update && sudo apt install -y "${SYSTEM_PACKAGES[@]}"

    - name: Install Python dependencies
      run: |
        EDITABLE=
        if [ "${{ inputs.relative }}" == "true" ]; then EDITABLE=-e ; fi

        python -m pip install -U pip
        pip install -U setuptools wheel
        pip install ${EDITABLE}.${{ inputs.install_extras }}
        pip install git+https://github.com/SINTEF/ci-cd.git@v2.10.0
      env:
        PIP_INDEX_URL: ${{ inputs.pip_index_url_docs }}
        PIP_EXTRA_INDEX_URL: ${{ inputs.pip_extra_index_urls_docs }}

    - name: Update API Reference
      if: steps.determine_framework.outputs.framework == 'mkdocs' && inputs.update_python_api_ref
      run: |
        if [ -z "${{ inputs.package_dirs }}" ]; then
          echo "'package_dirs' MUST be supplied, since 'update_docs' and 'update_python_api_ref' were set to 'true' and using the MkDocs framework."
          exit 1
        fi

        DEBUG=
        RELATIVE=
        if [ "${{ inputs.debug }}" == "true" ]; then DEBUG=--debug; fi
        if [ "${{ inputs.relative }}" == "true" ]; then RELATIVE=--relative; fi

        PACKAGE_DIRS=()
        UNWANTED_FOLDERS=()
        UNWANTED_FILES=()
        FULL_DOCS_FOLDERS=()
        FULL_DOCS_FILES=()
        SPECIAL_OPTIONS=()
        while IFS= read -r line; do
          if [ -n "${line}" ]; then PACKAGE_DIRS+=(--package-dir="${line}"); fi
        done <<< "${{ inputs.package_dirs }}"
        while IFS= read -r line; do
          if [ -n "${line}" ]; then UNWANTED_FOLDERS+=(--unwanted-folder="${line}"); fi
        done <<< "${{ inputs.exclude_dirs }}"
        while IFS= read -r line; do
          if [ -n "${line}" ]; then UNWANTED_FILES+=(--unwanted-file="${line}"); fi
        done <<< "${{ inputs.exclude_files }}"
        while IFS= read -r line; do
          if [ -n "${line}" ]; then FULL_DOCS_FOLDERS+=(--full-docs-folder="${line}"); fi
        done <<< "${{ inputs.full_docs_dirs }}"
        while IFS= read -r line; do
          if [ -n "${line}" ]; then FULL_DOCS_FILES+=(--full-docs-file="${line}"); fi
        done <<< "${{ inputs.full_docs_files }}"
        while IFS= read -r line; do
          if [ -n "${line}" ]; then SPECIAL_OPTIONS+=(--special-option="${line}"); fi
        done <<< "${{ inputs.special_file_api_ref_options }}"

        ci-cd create-api-reference-docs ${DEBUG} ${RELATIVE} \
          --pre-clean \
          --root-repo-path=${PWD} \
          "${PACKAGE_DIRS[@]}" \
          "${UNWANTED_FOLDERS[@]}" \
          "${UNWANTED_FILES[@]}" \
          "${FULL_DOCS_FOLDERS[@]}" \
          "${FULL_DOCS_FILES[@]}" \
          "${SPECIAL_OPTIONS[@]}"

    - name: Update landing page
      if: steps.determine_framework.outputs.framework == 'mkdocs' && inputs.update_docs_landing_page
      run: |
        # Ensure the default replacement for LICENSE linking works with a custom
        # separator
        LANDING_PAGE_REPLACEMENTS="${{ inputs.landing_page_replacements }}"
        if [ "${{ inputs.landing_page_replacement_separator }}" != "," ] && [ "${{ inputs.landing_page_replacements }}" == "(LICENSE),(LICENSE.md)" ]; then
          LANDING_PAGE_REPLACEMENTS="${LANDING_PAGE_REPLACEMENTS/,/${{ inputs.landing_page_replacement_separator }}}"
        fi

        REPLACEMENTS=()
        while IFS= read -r line; do
          if [ -n "${line}" ]; then REPLACEMENTS+=(--replacement="${line}"); fi
        done <<< "${LANDING_PAGE_REPLACEMENTS}"

        ci-cd create-docs-index \
          --root-repo-path=${PWD} \
          --replacement-separator="${{ inputs.landing_page_replacement_separator }}" \
          "${REPLACEMENTS[@]}"

    - name: Build documentation
      run: |
        # Set STRICT option

        if [ "${{ inputs.warnings_as_errors }}" == "true" ]; then
          if [ "${{ steps.determine_framework.outputs.framework }}" == "mkdocs" ]; then
            STRICT="--strict"
          elif [ "${{ steps.determine_framework.outputs.framework }}" == "sphinx" ]; then
            STRICT="-W"
          else
            echo "Unknown framework: ${{ steps.determine_framework.outputs.framework }}"
            exit 1
          fi

        else
          STRICT=
          echo "::warning file=ci_tests.yml,line=467,col=11,endColumn=18::Beware that the documentation may succeed building, but will not be rendered or built as intended. To ensure this is the case, set 'warnings_as_errors' to 'true' (using '--strict' (MkDocs) or '-W' (Sphinx))."
        fi

        # Run build command

        if [ "${{ steps.determine_framework.outputs.framework }}" == "mkdocs" ]; then
          mkdocs build ${STRICT}

        elif [ "${{ steps.determine_framework.outputs.framework }}" == "sphinx" ]; then
          if [[ "${{ inputs.sphinx-build_options }}" =~ \n ]]; then
            # Expected to be a multi-line string
            SPHINX_OPTIONS=()
            while IFS= read -r line; do
              if [ -n "${line}" ]; then SPHINX_OPTIONS+=("${line}"); fi
            done <<< "${{ inputs.sphinx-build_options }}"
          else
            # Expected to be a single-line string
            SPHINX_OPTIONS=(${{ inputs.sphinx-build_options }})
          fi

          sphinx-build ${STRICT} \
            "${SPHINX_OPTIONS[@]}" \
            ${{ inputs.docs_folder }} ${{ inputs.build_target_folder }}

        else
          echo "Unknown framework: ${{ steps.determine_framework.outputs.framework }}"
          exit 1
        fi