path: root/.github/workflows/doc-rules-compose.yaml

---
name: Composeable Required doc-rules Verify

# yamllint disable-line rule:truthy
on:
  workflow_call:
    inputs:
      GERRIT_BRANCH:
        description: "Branch that change is against"
        required: true
        type: string
      GERRIT_CHANGE_ID:
        description: "The ID for the change"
        required: true
        type: string
      GERRIT_CHANGE_NUMBER:
        description: "The Gerrit number"
        required: true
        type: string
      GERRIT_CHANGE_URL:
        description: "URL to the change"
        required: true
        type: string
      GERRIT_EVENT_TYPE:
        description: "Type of Gerrit event"
        required: true
        type: string
      GERRIT_PATCHSET_NUMBER:
        description: "The patch number for the change"
        required: true
        type: string
      GERRIT_PATCHSET_REVISION:
        description: "The revision sha"
        required: true
        type: string
      GERRIT_PROJECT:
        description: "Project in Gerrit"
        required: true
        type: string
      GERRIT_REFSPEC:
        description: "Gerrit refspec of change"
        required: true
        type: string
      TARGET_REPO:
        # yamllint disable-line rule:line-length
        description: "The target GitHub repository needing the required workflow"
        required: true
        type: string
    secrets:
      GERRIT_SSH_REQUIRED_PRIVKEY:
        description: "SSH Key for the authorized user account"
        required: true

concurrency:
  # yamllint disable-line rule:line-length
  group: compose-required-doc-rules-${{ github.workflow }}-${{ github.event.inputs.GERRIT_CHANGE_ID || github.run_id }}
  cancel-in-progress: true

env:
  DOCS_FOUND: true

jobs:
  doc-rules-validation:
    runs-on: ubuntu-latest
    steps:
      - name: Gerrit Checkout
        # yamllint disable-line rule:line-length
        uses: lfit/checkout-gerrit-change-action@57bf0435f739fbbc7ce4cc85c9c3b8a386c6f84b  # v0.6
        with:
          gerrit-refspec: ${{ inputs.GERRIT_REFSPEC }}
          gerrit-project: ${{ inputs.GERRIT_PROJECT }}
          gerrit-url: ${{ vars.GERRIT_URL }}
          delay: "0s"
          repository: ${{ inputs.TARGET_REPO }}
          ref: refs/heads/${{ inputs.GERRIT_BRANCH }}
      - uses: actions/setup-python@v4
        id: setup-python
        with:
          python-version: "3.11"
      - name: Clone git submodules
        run: git submodule update --init
      - name: Start doc-rules Verify and setting values
        # yamllint disable rule:line-length
        run: |
          . /lib/lsb/init-functions || exit 0
          echo "exitstatus=0" >> "$GITHUB_ENV"
          echo "warning=0" >> "$GITHUB_ENV"
          # message, begin
          log_success_msg "INFO doc-rules Version 23-07-07-A"
          log_success_msg "INFO Starting additional checks related to documentation."
          log_success_msg "INFO See https://git.onap.org/doc/doc-best-practice for example config files (master branch)."
          log_success_msg "INFO Modify example config files if you like to use them in a release branch."
          log_success_msg "INFO See https://wiki.onap.org/x/w4IEBw for the detailed procedure #02."
          log_success_msg "INFO In case of questions please contact the ONAP documentation team."
      - name: Checking docs directory
        run: |
          # docs directory
          . /lib/lsb/init-functions || exit 0
          if [ ! -d docs ] ; then
            log_success_msg "INFO Directory docs not found. Skipping further checks."
            echo "DOCS_FOUND=false" >> "$GITHUB_ENV"
          fi
      - name: Checking config files
        if: ${{ env.DOCS_FOUND == 'true' }}
        run: |
          # config files, required
          . /lib/lsb/init-functions || exit 0
          for i in docs/index.rst docs/conf.py docs/requirements-docs.txt docs/_static/css/ribbon.css .readthedocs.yaml; do
            if [ ! -f $i ] ; then
              log_failure_msg "FAIL $i missing. Please add it or remove the full docs directory."
              echo "exitstatus=1" >> "$GITHUB_ENV"
            else
              log_success_msg "INFO $i found."
            fi
          done
          # config files, no longer required
          # shellcheck disable=SC2043
          for i in docs/conf.yaml; do
            if [ -f $i ] ; then
              log_failure_msg "FAIL $i found. It is no longer required. Please remove it."
              echo "exitstatus=1" >> "$GITHUB_ENV"
            else
              log_success_msg "INFO $i not found."
            fi
          done
      - name: Checking tox.ini
        if: ${{ env.DOCS_FOUND == 'true' }}
        run: |
          # tox.ini @ docs directory
          . /lib/lsb/init-functions || exit 0
          filename="docs/tox.ini"
          if [ ! -f $filename ] ; then
            log_failure_msg "FAIL $filename missing. Please add it or remove the full docs directory."
            echo "exitstatus=1" >> "$GITHUB_ENV"
          else
            log_success_msg "INFO $filename found."
            # sphinx-build command and -W option
            sphinxbuild_detected=0
            linenumber=0
            while IFS="" read -r line || [ -n "$line" ] ; do
              linenumber=$((linenumber+1))
              if echo "$line" | grep -q '^[ \t]*sphinx-build.*' ; then
                sphinxbuild_detected="1"
                if echo "$line" | grep -q '^[ \t]*sphinx-build.* -W ' ; then
                  log_success_msg "INFO sphinx-build option '-W' used in $filename, line $linenumber."
                elif echo "$line" | grep -q ' \-b spelling ' ; then
                  log_warning_msg "WARN sphinx-build option '-W' missing for spellcheck in $filename, line $linenumber."
                  echo "warning=1" >> "$GITHUB_ENV"
                else
                  log_warning_msg "WARN sphinx-build option '-W' missing in $filename, line $linenumber. Please add it."
                  echo "warning=1" >> "$GITHUB_ENV"
                  #log_failure_msg "FAIL sphinx-build option '-W' missing in $filename, line $linenumber. Please add it."
                  #echo "exitstatus=1" >> "$GITHUB_ENV"
                fi
              fi
            done < $filename
            if [ "$sphinxbuild_detected" = "0" ]; then
              log_warning_msg "WARN Sphinx-build command(s) missing in $filename. Please add it."
              echo "warning=1" >> "$GITHUB_ENV"
              #log_failure_msg "FAIL Sphinx-build command(s) missing in $filename. Please add it."
              #echo "exitstatus=1" >> "$GITHUB_ENV"
            fi
            # second tox.ini @ root directory
            if [ -f ./tox.ini ] ; then
              # sphinx-build command
              # shellcheck disable=SC2002
              if cat ./tox.ini | grep -q '^[ \t]*sphinx-build.*' ; then
                log_warning_msg "WARN tox.ini also exists in root directory and contains sphinx-build command(s). Please check for redundancies."
                echo "warning=1" >> "$GITHUB_ENV"
              fi
            fi
            unset sphinxbuild_detected
            unset linenumber
          fi
          unset filename
      - name: Checking ribbon.css
        if: ${{ env.DOCS_FOUND == 'true' }}
        run: |
          # ribbon.css
          . /lib/lsb/init-functions || exit 0
          filename="docs/_static/css/ribbon.css"
          if [ ! -f $filename ]; then
            log_failure_msg "FAIL $filename missing. Please add it or remove the full docs directory."
            echo "exitstatus=1" >> "$GITHUB_ENV"
          else
            log_success_msg "INFO $filename found."
            # max-width parameter
            cssmaxwidth=$(grep '^[ \t]*max-width:' $filename | sed -e 's/^[ \t]*//' | sed -e 's/;$//');
            if [[ ! $cssmaxwidth == *"max-width: 800px"* ]]; then
              log_failure_msg "FAIL Setting 'max-width: 800px' missing in $filename. Please add it."
              echo "exitstatus=1" >> "$GITHUB_ENV"
            else
              log_success_msg "INFO Setting 'max-width: 800px' found in $filename."
            fi
            unset cssmaxwidth
          fi
          unset filename
      - name: Checking readthedocs.yaml
        if: ${{ env.DOCS_FOUND == 'true' }}
        run: |
          # readthedocs.yaml
          . /lib/lsb/init-functions || exit 0
          filename=".readthedocs.yaml"
          if [ ! -f $filename ]; then
            log_failure_msg "FAIL $filename missing. Please add it or remove the full docs directory."
            echo "exitstatus=1" >> "$GITHUB_ENV"
          else
            log_success_msg "INFO $filename found."
            # obsolete parameter: (build:) image: latest
            buildimage=$(grep '^[ \t]*image:' $filename | sed -e 's/^[ \t]*//' | sed -e 's/;$//');
            if [[ $buildimage == *"latest"* ]]; then
              log_failure_msg "FAIL Setting '(build: image:) latest' found in $filename. Please remove it."
              echo "exitstatus=1" >> "$GITHUB_ENV"
            else
              log_success_msg "INFO Setting '(build: image:) latest' not found in $filename."
            fi
            unset buildimage
            # obsolete parameter: (python:) version: 3.7
            pythonversion=$(grep '^[ \t]*version:' $filename | sed -e 's/^[ \t]*//' | sed -e 's/;$//');
            if [[ $pythonversion == *"3.7"* ]]; then
              log_failure_msg "FAIL Setting '(python:) version: 3.7' found in $filename. Please remove it."
              echo "exitstatus=1" >> "$GITHUB_ENV"
            else
              log_success_msg "INFO Setting '(python:) version: 3.7' not found in $filename."
            fi
            unset pythonversion
            # obsolete parameter: submodules:
            submodules=$(grep '^[ \t]*submodules:' $filename | sed -e 's/^[ \t]*//' | sed -e 's/;$//');
            if [[ $submodules == *"submodules:"* ]]; then
              log_failure_msg "FAIL Setting 'submodules:' found in $filename. Please remove it."
              echo "exitstatus=1" >> "$GITHUB_ENV"
            else
              log_success_msg "INFO Setting 'submodules:' not found in $filename."
            fi
            unset submodules
            # required parameter: (build:) os:
            buildos=$(grep '^[ \t]*os:' $filename | sed -e 's/^[ \t]*//' | sed -e 's/;$//');
            if [[ ! $buildos == *"ubuntu-20.04"* ]]; then
              log_failure_msg "FAIL Setting '(build:) os: ubuntu-20.04' missing in $filename. Please add it."
              echo "exitstatus=1" >> "$GITHUB_ENV"
            else
              log_success_msg "INFO Setting '(build:) os: ubuntu-20.04' found in $filename."
            fi
            unset buildos
            # required parameter: (build: tools:) python
            buildtoolspython=$(grep '^[ \t]*python:' $filename | sed -e 's/^[ \t]*//' | sed -e 's/;$//');
            if [[ ! $buildtoolspython == *\"3.8\"* ]]; then
              log_failure_msg "FAIL Setting '(build: tools:) python: \"3.8\"' missing in $filename. Please add it."
              echo "exitstatus=1" >> "$GITHUB_ENV"
            else
              log_success_msg "INFO Setting '(build: tools:) python: \"3.8\"' found in $filename."
            fi
            unset buildtoolspython
          fi
          unset filename
      - name: Finish doc-rules Verify
        if: ${{ env.DOCS_FOUND == 'true' }}
        run: |
          # message, end
          . /lib/lsb/init-functions || exit 0
          if [ "${{ env.exitstatus }}" = "0" ]; then
            if [ "${{ env.warning }}" = "0" ]; then
              log_success_msg "INFO Congratulations! No documentation problem(s) detected."
            else
              log_warning_msg "WARN No major documentation problem(s) detected but there are warnings!"
            fi
          else
            if [ ! "${{ env.warning }}" = "0" ]; then
              log_warning_msg "WARN Please check the detected documentation warning(s)!"
            fi
            log_failure_msg "FAIL Please fix the detected documentation problem(s)!"
          fi
          # shellcheck disable=SC2242
          exit "${{ env.exitstatus }}"