Automate documentation releases

.github/utils/release_tag_msg.txt

@@ -0,0 +1,7 @@
+TAG_NAME
+
+See the
+[versioned online documentation](https://emmo-repo.github.io/EMMO-python/TAG_NAME)
+for more information.
+The full changelog can be seen
+[here](https://emmo-repo.github.io/EMMO-python/TAG_NAME/CHANGELOG).

.github/workflows/cd_docs.yml

@@ -0,0 +1,66 @@
+name: CD Documentation
+
+on:
+  push:
+    branches: [master]
+
+jobs:
+  deploy:
+    name: Deploy `latest` documentation
+    if: github.repository_owner == 'emmo-repo'
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Release check
+      run: |
+        COMMIT_MSG="$(gh api /repos/${{ github.repository}}/commits/master --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@v2
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python 3.7
+      if: env.RELEASE_RUN == 'false'
+      uses: actions/setup-python@v2
+      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 "EMMOntoPy Developers"
+        git config --global user.email "EMMOntoPy@emmo.info"
+
+    - 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 "The following files in the documentation has not been committed:"
+          git status --porcelain docs/api_reference docs/index.md
+          exit 1
+        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 master

.github/workflows/cd_publish.yml

@@ -0,0 +1,150 @@
+name: Release new EMMOntoPy version
+
+on:
+  release:
+    types: [published]
+
+env:
+  PUBLISH_UPDATE_BRANCH: master
+  GIT_USER_NAME: EMMOntoPy Developers
+  GIT_USER_EMAIL: EMMOntoPy@emmo.info
+  # IMPORTANT: The tag should *not* be prepended by `v`,
+  # i.e., it should be `1.0.1` and not `v1.0.1`.
+
+jobs:
+  update-version:
+    name: Update CHANGELOG and documentation
+    if: github.repository == 'emmo-repo/EMMO-python'
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python 3.7
+      uses: actions/setup-python@v2
+      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 "${GIT_USER_NAME}"
+        git config --global user.email "${GIT_USER_EMAIL"
+
+    - name: Update changelog
+      uses: CharMixer/auto-changelog-action@v1
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        release_branch: ${{ env.PUBLISH_UPDATE_BRANCH }}
+
+    - name: Update version and tag
+      run: |
+        NEW_VERSION="${GITHUB_REF#refs/tags/}"
+
+        invoke setver --ver="${NEW_VERSION}"
+        git add ontopy/__init__.py CHANGELOG.md
+        git commit -m "Release v${NEW_VERSION}"
+
+        TAG_MSG=.github/utils/release_tag_msg.txt
+        sed -i "s|TAG_NAME|${NEW_VERSION}|" "${TAG_MSG}"
+        git tag -af -F "${TAG_MSG}" ${NEW_VERSION}
+
+    - name: Push new commit and update tag
+      uses: ad-m/github-push-action@master
+      with:
+        github_token: ${{ secrets.GITHUB_TOKEN }}
+        branch: ${{ env.PUBLISH_UPDATE_BRANCH }}
+        force: true
+        tags: true
+
+    - name: Get tagged versions
+      run: echo "PREVIOUS_VERSION=$(git tag -l --sort -version:refname | sed -n 2p)" >> $GITHUB_ENV
+
+    - name: Create release-specific changelog
+      uses: CharMixer/auto-changelog-action@v1
+      with:
+        token: ${{ secrets.GITHUB_TOKEN }}
+        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.GITHUB_TOKEN }}
+
+  publish-package:
+    name: Publish Python package to PyPI
+    runs-on: ubuntu-latest
+    needs: update-version
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+      with:
+        fetch-depth: 2
+        ref: ${{ env.PUBLISH_UPDATE_BRANCH }}
+
+    - name: Set up Python 3.7
+      uses: actions/setup-python@v2
+      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: 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: publish-package
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+      with:
+        fetch-depth: 0
+        ref: ${{ env.PUBLISH_UPDATE_BRANCH }}
+
+    - name: Set up Python 3.7
+      uses: actions/setup-python@v2
+      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/} stable
+        mike deploy --push --remote origin --branch gh-pages --update-aliases --config-file mkdocs.yml latest ${{ env.PUBLISH_UPDATE_BRANCH }}

.github/workflows/ci_workflow.yml

@@ -65,8 +65,8 @@ jobs:
         #python step4_map_instance.py
         cd -
 
-  documentation:
-    name: EMMO documentation
+  ontodoc:
+    name: EMMO documentation (test using ontodoc)
     runs-on: ubuntu-latest
     steps:
     - uses: actions/checkout@v2.3.4
@@ -162,3 +162,48 @@ jobs:
         mkdir -p /tmp/installation_dir
         cd /tmp/installation_dir
         pip install ${ORIGINAL_PWD}/${BDIST_DIR}/${{ env.BDIST_FILE }}
+
+  documentation:
+    name: Check documentation
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+
+    - name: Set up Python 3.7
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.7
+
+    - name: Install dependencies
+      run: |
+        python -m pip install --upgrade pip
+        pip install -U setuptools wheel
+        pip install -U -e .[docs]
+
+    - name: Set up git user
+      run: |
+        git config --global user.name "EMMOntoPy Developers"
+        git config --global user.email "EMMOntoPy@emmo.info"
+
+    - name: Check API Reference and landing page
+      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: Build check
+      run: mkdocs build --strict --verbose