Merge pull request #485 from emmo-repo/cwa/fix-481-482-ci-cd-workflows

Makeover for CI/CD workflows, pre-commit & MkDocs.

This PR implements a complete makeover for the CI/CD
workflows, utilizing the SINTEF/ci-cd callable GitHub Actions
workflows as well as the pre-commit hooks there.
ci-cd: https://github.com/SINTEF/ci-cd

Some updates in the MkDocs configuration were necessary
to fix some presentation issues of certain documentation pages.
The table of contents has been improved to exclude the
emmodoc markdown template files under the "Examples" section.

The EMMC-CSA reference on the landing page has been updated
to mention EMMC-ASBL and point to emmc.eu instead of the defunkt
emmc.info web page. Furthermore, the logo reference has been fixed
to point to a local PNG image.

.github/workflows/cd_publish.yml

@@ -4,121 +4,32 @@ on:
   release:
     types: [published]
 
-env:
-  PUBLISH_UPDATE_BRANCH: master
-  GIT_USER_NAME: EMMOntoPy Developers
-  GIT_USER_EMAIL: "Team4.0@SINTEF.no"
-
 jobs:
-  update-and-publish:
-    name: Update CHANGELOG and documentation
-    if: github.repository == 'emmo-repo/EMMOntoPy'
-    runs-on: ubuntu-latest
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-
-    - name: Set up Python 3.7
-      uses: actions/setup-python@v4
-      with:
-        python-version: 3.7
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install setuptools wheel
-        pip install -U -e .[dev]
-
-    - name: Set up git user
-      run: |
-        git config --global user.name "${GIT_USER_NAME}"
-        git config --global user.email "${GIT_USER_EMAIL}"
-
-    - name: Update changelog
-      uses: CharMixer/auto-changelog-action@v1
-      with:
-        token: ${{ secrets.RELEASE_PAT }}
-        release_branch: ${{ env.PUBLISH_UPDATE_BRANCH }}
-
-    - name: Update version and tag
-      run: |
-        invoke setver --ver="${GITHUB_REF#refs/tags/}"
-        git add ontopy/__init__.py CHANGELOG.md
-        git commit -m "Release ${GITHUB_REF#refs/tags/}"
-
-        TAG_MSG=.github/utils/release_tag_msg.txt
-        sed -i "s|TAG_NAME|${GITHUB_REF#refs/tags/}|" "${TAG_MSG}"
-        git tag -af -F "${TAG_MSG}" ${GITHUB_REF#refs/tags/}
-
-    - name: Push new commit and update tag
-      uses: CasperWA/push-protected@v2
-      with:
-        token: ${{ secrets.RELEASE_PAT }}
-        branch: ${{ env.PUBLISH_UPDATE_BRANCH }}
-        force: true
-        tags: true
-        unprotect_reviews: true
-
-    - name: Get tagged versions
-      run: echo "PREVIOUS_VERSION=$(git tag -l --sort -version:refname | grep -E "^v0\.[1-8].*$" | sed -n 2p)" >> $GITHUB_ENV
-
-    - name: Create release-specific changelog
-      uses: CharMixer/auto-changelog-action@v1
-      with:
-        token: ${{ secrets.RELEASE_PAT }}
-        release_branch: ${{ env.PUBLISH_UPDATE_BRANCH }}
-        since_tag: "${{ env.PREVIOUS_VERSION }}"
-        output: "release_changelog.md"
-
-    - name: Append changelog to release body
-      run: |
-        gh api /repos/${{ github.repository }}/releases/${{ github.event.release.id }} --jq '.body' > release_body.md
-        cat release_changelog.md >> release_body.md
-        gh api /repos/${{ github.repository }}/releases/${{ github.event.release.id }} -X PATCH -F body='@release_body.md'
-      env:
-        GITHUB_TOKEN: ${{ secrets.RELEASE_PAT }}
-
-    - name: Build source and built distributions
-      run: python setup.py sdist bdist_wheel
-
-    - name: Publish to PyPI
-      uses: pypa/gh-action-pypi-publish@master
-      with:
-        user: __token__
-        password: ${{ secrets.PYPI_TOKEN }}
-
-  deploy-docs:
-    name: Deploy new documentation
-    runs-on: ubuntu-latest
-    needs: update-and-publish
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-        ref: ${{ env.PUBLISH_UPDATE_BRANCH }}
-
-    - name: Set up Python 3.7
-      uses: actions/setup-python@v4
-      with:
-        python-version: 3.7
-
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install setuptools wheel
-        pip install -U -e .[docs]
-
-    - name: Set up git user
-      run: |
-        git config --global user.name "${{ env.GIT_USER_NAME }}"
-        git config --global user.email "${{ env.GIT_USER_EMAIL }}"
-
-    - name: Deploy documentation
-      run: |
-        mike deploy --push --remote origin --branch gh-pages --update-aliases --config-file mkdocs.yml ${GITHUB_REF#refs/tags/v} stable
-        mike deploy --push --remote origin --branch gh-pages --update-aliases --config-file mkdocs.yml latest ${{ env.PUBLISH_UPDATE_BRANCH }}
+  publish:
+    name: External
+    uses: SINTEF/ci-cd/.github/workflows/cd_release.yml@v1
+    if: github.repository == 'emmo-repo/EMMOntoPy' && startsWith(github.ref, 'refs/tags/v')
+    with:
+      git_username: EMMOntoPy Developers
+      git_email: "Team4.0@SINTEF.no"
+      release_branch: master
+
+      # Publish package
+      python_package: true
+      python_version_build: "3.7"
+      # We're mentioning only 'ontopy', since the version is set statically only in
+      # ontopy/__init__.py
+      package_dirs: ontopy
+      install_extras: "[dev]"
+      build_cmd: "python -m build"
+      publish_on_pypi: true
+
+      # Update documentation
+      update_docs: true
+      python_version_docs: "3.7"
+      doc_extras: "[docs]"
+      changelog_exclude_labels: dependencies
+
+    secrets:
+      PyPI_token: ${{ secrets.PYPI_TOKEN }}
+      PAT: ${{ secrets.RELEASE_PAT }}

.github/workflows/ci_automerge_dependabot.yml

@@ -6,25 +6,8 @@ on:
 
 jobs:
   update-dependabot-branch:
-    name: Update permanent dependabot branch
+    name: External
+    uses: SINTEF/ci-cd/.github/workflows/ci_automerge_prs.yml@v1
     if: github.repository_owner == 'emmo-repo' && startsWith(github.event.pull_request.head.ref, 'dependabot/') && github.actor == 'dependabot[bot]'
-    runs-on: ubuntu-latest
-
-    env:
-      DEPENDABOT_BRANCH: ci/dependabot-updates
-      GIT_USER_NAME: EMMOntoPy Developers
-      GIT_USER_EMAIL: "Team4.0@SINTEF.no"
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-        ref: ${{ github.event.pull_request.head.ref }}
-
-    - name: Activate auto-merge
-      run: |
-        PR_ID="$(gh api graphql -F owner='{owner}' -F name='{repo}' -f query='query($owner: String!, $name: String!) {repository(owner: $owner, name: $name) {pullRequest(number: ${{ github.event.pull_request.number }}) {id}}}' --jq '.data.repository.pullRequest.id')"
-        gh api graphql -f pr_id="$PR_ID" -f query='mutation($pr_id: ID!) {enablePullRequestAutoMerge(input:{mergeMethod:SQUASH,pullRequestId:$pr_id }) {pullRequest {number}}}'
-      env:
-        GITHUB_TOKEN: ${{ secrets.RELEASE_PAT }}
+    secrets:
+      PAT: ${{ secrets.RELEASE_PAT }}

.github/workflows/ci_cd_updated_master.yml

@@ -4,122 +4,28 @@ on:
   push:
     branches: [master]
 
-env:
-  DEPENDABOT_BRANCH: ci/dependabot-updates
-  GIT_USER_NAME: EMMOntoPy Developers
-  GIT_USER_EMAIL: "Team4.0@SINTEF.no"
-  DEFAULT_REPO_BRANCH: master
-
 jobs:
-  update-dependabot-branch:
-    name: Update permanent dependabot branch
-    if: github.repository_owner == 'emmo-repo'
-    runs-on: ubuntu-latest
-
-    steps:
-    - name: Checkout repository
-      uses: actions/checkout@v3
-      with:
-        ref: ${{ env.DEPENDABOT_BRANCH }}
-        fetch-depth: 0
-
-    - name: Set up git config
-      run: |
-        git config --global user.name "${{ env.GIT_USER_NAME }}"
-        git config --global user.email "${{ env.GIT_USER_EMAIL }}"
-
-    - name: Update '${{ env.DEPENDABOT_BRANCH }}'
-      run: |
-        git fetch origin
-
-        LATEST_PR_BODY="$(gh api /repos/${{ github.repository}}/pulls -X GET -f state=closed -f per_page=1 -f sort=updated -f direction=desc --jq '.[].body')"
-        cat .github/utils/single_dependency_pr_body.txt | head -8 > .tmp_file.txt
-        if [ -z "$(printf '%s\n' "${LATEST_PR_BODY}" | head -8 | diff - .tmp_file.txt --strip-trailing-cr)" ]; then
-          # The dependency branch has just been merged into `${{ env.DEFAULT_REPO_BRANCH }}`
-          # The dependency branch should be reset to `${{ env.DEFAULT_REPO_BRANCH }}`
-          echo "The dependencies have just been updated! Reset to ${{ env.DEFAULT_REPO_BRANCH }}."
-          git reset --hard origin/${{ env.DEFAULT_REPO_BRANCH }}
-          echo "FORCE_PUSH=yes" >> $GITHUB_ENV
-        else
-          # Normal procedure: Merge `${{ env.DEFAULT_REPO_BRANCH }}` into `${{ env.DEPENDABOT_BRANCH }}`
-          echo "Merge new updates to ${{ env.DEFAULT_REPO_BRANCH }} into ${{ env.DEPENDABOT_BRANCH }}"
-          git merge -m "Keep '${{ env.DEPENDABOT_BRANCH }}' up-to-date with '${{ env.DEFAULT_REPO_BRANCH }}'" origin/${{ env.DEFAULT_REPO_BRANCH }}
-          echo "FORCE_PUSH=no" >> $GITHUB_ENV
-        fi
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: Push to '${{ env.DEPENDABOT_BRANCH }}'
-      uses: CasperWA/push-protected@v2
-      with:
-        token: ${{ secrets.RELEASE_PAT }}
-        branch: ${{ env.DEPENDABOT_BRANCH }}
-        sleep: 15
-        force: ${{ env.FORCE_PUSH }}
-
-  deploy-docs:
-    name: Deploy `latest` documentation
+  updates-to-master:
+    name: External
+    uses: SINTEF/ci-cd/.github/workflows/ci_cd_updated_default_branch.yml@v1
     if: github.repository_owner == 'emmo-repo'
-    runs-on: ubuntu-latest
-
-    steps:
-    - name: Release check
-      run: |
-        COMMIT_MSG="$(gh api /repos/${{ github.repository}}/commits/${{ env.DEFAULT_REPO_BRANCH }} --jq '.commit.message')"
-        if [[ "${COMMIT_MSG}" =~ ^Release\ v.*$ ]]; then
-          echo "In a release - do not run this job !"
-          echo "RELEASE_RUN=true" >> $GITHUB_ENV
-        else
-          echo "Not a release - update docs"
-          echo "RELEASE_RUN=false" >> $GITHUB_ENV
-        fi
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-
-    - name: Checkout repository
-      if: env.RELEASE_RUN == 'false'
-      uses: actions/checkout@v3
-      with:
-        fetch-depth: 0
-
-    - name: Set up Python 3.7
-      if: env.RELEASE_RUN == 'false'
-      uses: actions/setup-python@v4
-      with:
-        python-version: 3.7
-
-    - name: Install dependencies
-      if: env.RELEASE_RUN == 'false'
-      run: |
-        python -m pip install --upgrade pip
-        pip install -U setuptools wheel
-        pip install -U -e .[docs]
-
-    - name: Set up git user
-      if: env.RELEASE_RUN == 'false'
-      run: |
-        git config --global user.name "${{ env.GIT_USER_NAME }}"
-        git config --global user.email "${{ env.GIT_USER_EMAIL }}"
-
-    - name: Check API Reference and landing page
-      if: env.RELEASE_RUN == 'false'
-      run: |
-        invoke create-api-reference-docs --pre-clean
-        invoke create-docs-index
-
-        if [ -n "$(git status --porcelain docs/api_reference docs/index.md)" ]; then
-          echo -e "\u274c Discrepancies found !"
-          echo -e "The following files in the documentation must be committed:"
-          git status --porcelain docs/api_reference docs/index.md
-          echo -e "\nRun:\n"
-          echo "    invoke create-api-reference-docs --pre-clean"
-          echo -e "    invoke create-docs-index\n"
-          echo "And commit the changed files."
-          exit 1
-        else
-          echo -e "\u2705 All good !"
-        fi
-
-    - name: Deploy documentation
-      if: env.RELEASE_RUN == 'false'
-      run: mike deploy --push --remote origin --branch gh-pages --update-aliases --config-file mkdocs.yml latest ${{ env.DEFAULT_REPO_BRANCH }}
+    with:
+      git_username: EMMOntoPy Developers
+      git_email: "Team4.0@SINTEF.no"
+      permanent_dependencies_branch: ci/dependabot-updates
+      default_repo_branch: master
+
+      # Update documentation
+      update_docs: true
+      update_python_api_ref: true
+      update_docs_landing_page: true
+      package_dirs: |
+        emmopy
+        ontopy
+      python_version: "3.7"
+      doc_extras: "[docs]"
+      special_file_api_ref_options: "emmopy/emmocheck.py,show_bases: false"
+      landing_page_replacements: |
+        (LICENSE.txt),(LICENSE.md)
+        (tools),(../tools)
+      changelog_exclude_labels: dependencies