feat: add workflow to publish code documentation to the Github Wiki upon package releases (#396)

Co-authored-by: Marcel Rodrigues <marcelgmr@gmail.com>

Author: jenstroeger

.github/workflows/_build.yaml

@@ -110,8 +110,9 @@ jobs:
         REQUIREMENTS_PATH=$(find dist/ -type f -name "*-requirements.txt")
         SBOM_PATH=$(find dist/ -type f -name "*-sbom.json")
         HTML_DOCS_PATH=$(find dist/ -type f -name "*-docs-html.zip")
+        MARKDOWN_DOCS_PATH=$(find dist/ -type f -name "*-docs-md.zip")
         BUILD_EPOCH_PATH=$(find dist/ -type f -name "*-build-epoch.txt")
-        DIGEST=$(sha256sum "$TARBALL_PATH" "$WHEEL_PATH" "$REQUIREMENTS_PATH" "$SBOM_PATH" "$HTML_DOCS_PATH" "$BUILD_EPOCH_PATH" | base64 -w0)
+        DIGEST=$(sha256sum "$TARBALL_PATH" "$WHEEL_PATH" "$REQUIREMENTS_PATH" "$SBOM_PATH" "$HTML_DOCS_PATH" "$MARKDOWN_DOCS_PATH" "$BUILD_EPOCH_PATH" | base64 -w0)
         echo "Digest of artifacts is $DIGEST."
         echo "artifacts-sha256=$DIGEST" >> "$GITHUB_OUTPUT"
 

.github/workflows/_wiki-documentation.yaml

@@ -0,0 +1,85 @@
+# This reusable workflow publishes Markdown docs to Github Wiki. Some manual
+# setup is required before using it: enable Wiki in repository and create at
+# least one page.
+
+name: Publish Github Wiki documentation
+on:
+  workflow_call:
+    inputs:
+      release_tag:
+        required: true
+        type: string
+      release_url:
+        required: true
+        type: string
+      artifact_name:
+        required: true
+        type: string
+      git_user_name:
+        required: true
+        type: string
+      git_user_email:
+        required: true
+        type: string
+    secrets:
+      REPO_ACCESS_TOKEN:
+        required: true
+
+permissions:
+  contents: read
+
+jobs:
+  publish-wiki:
+    name: Publish Github Wiki
+    if: github.repository.has_wiki == true
+    runs-on: ubuntu-latest
+    steps:
+
+    - name: Harden Runner
+      uses: step-security/harden-runner@2e205a28d0e1da00c5f53b161f4067b052c61f34 # v1.5.0
+      with:
+        egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
+
+    # Check out the repository's Wiki repo into the wiki/ folder. The token is required
+    # only for private repositories.
+    - name: Check out repository
+      uses: actions/checkout@93ea575cb5d8a053eaa0ac8fa3b40d7e05a33cc8 # v3.1.0
+      with:
+        token: ${{ secrets.REPO_ACCESS_TOKEN }}
+        repository: ${{ format('{0}.wiki', github.repository) }}
+        path: wiki
+
+    # Download the build artifacts attached to this workflow run.
+    - name: Download artifact
+      uses: actions/download-artifact@9782bd6a9848b53b110e712e20e42d89988822b7 # v3.0.1
+      with:
+        name: ${{ inputs.artifact_name }}
+        path: dist
+
+    # Unpack the Markdown docs into the Wiki repository. Delete existing files first
+    # to ensure that no stale files stay behind.
+    - name: Copy Markdown documentation
+      run: |
+        mkdir docs/
+        unzip -d docs/ "$(ls dist/*-docs-md.zip)"
+        rm --recursive --force wiki/*
+        cp --recursive --verbose --target-directory wiki/ docs/markdown/*
+
+    # If there was any change to the Wiki then push the update.
+    - name: Push to Wiki
+      run: |
+        cd wiki/
+        if [ -n "$(git status --porcelain)" ]; then
+          git add .
+          git config --global user.name "$USER_NAME"
+          git config --global user.email "$USER_EMAIL"
+          git commit --message "$WIKI_COMMIT_MESSAGE"
+          git push
+        fi
+      env:
+        USER_NAME: ${{ inputs.git_user_name }}
+        USER_EMAIL: ${{ inputs.git_user_email }}
+        WIKI_COMMIT_MESSAGE: |
+          docs: update for ${{ inputs.release_tag }}
+
+          Link: ${{ inputs.release_url }}

.github/workflows/release.yaml

@@ -10,6 +10,7 @@ on:
 permissions:
   contents: read
 env:
+  # Duplicate these values for the `wiki` job below!
   ARTIFACT_NAME: artifact-ubuntu-latest-python-3.10
   # This is the username and email for the user who commits and pushes the release
   # commit. In an organisation that should be a dedicated devops account.
@@ -226,3 +227,24 @@ jobs:
       release_url: ${{ needs.release.outputs.release-url }}
     secrets:
       SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }}
+
+  # Publish the generated Markdown documentation to the repository's Wiki.
+  # Uncomment the `if` to disable generating Wiki documentation.
+  wiki:
+    # if: ${{ false }}
+    needs: [release]
+    name: Publish Github Wiki documentation
+    uses: ./.github/workflows/_wiki-documentation.yaml
+    permissions:
+      contents: read
+    with:
+      release_tag: ${{ needs.release.outputs.release-tag }}
+      release_url: ${{ needs.release.outputs.release-url }}
+      # Github disallows passing environment variables as arguments to a reusable
+      # workflow, so we have to duplicate these values here. Related discussion
+      # here: https://github.com/actions/toolkit/issues/931
+      artifact_name: artifact-ubuntu-latest-python-3.10
+      git_user_name: jenstroeger
+      git_user_email: jenstroeger@users.noreply.github.com
+    secrets:
+      REPO_ACCESS_TOKEN: ${{ secrets.REPO_ACCESS_TOKEN }}

Makefile

@@ -173,21 +173,34 @@ test:
 # When building these artifacts, we need the environment variable SOURCE_DATE_EPOCH
 # set to the build date/epoch. For more details, see: https://flit.pypa.io/en/latest/reproducible.html
 .PHONY: dist
-dist: dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt
+dist: dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-md.zip dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt
 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-py3-none-any.whl: check test
 	flit build --setup-py --format wheel
 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION).tar.gz: check test
 	flit build --setup-py --format sdist
-dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip: docs
-	python -m zipfile -c dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip docs/_build/html
+dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip: docs-html
+	python -m zipfile -c dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-html.zip docs/_build/html/
+dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-md.zip: docs-md
+	python -m zipfile -c dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-docs-md.zip docs/_build/markdown/
 dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt:
 	echo $(SOURCE_DATE_EPOCH) > dist/$(PACKAGE_NAME)-$(PACKAGE_VERSION)-build-epoch.txt
 
-# Build the HTML documentation from the package's source.
-.PHONY: docs
-docs: docs/_build/html/index.html
+# Build the HTML and Markdown documentation from the package's source.
+.PHONY: docs docs-html docs-md
+docs: docs-html docs-md
+docs-html: docs/_build/html/index.html
 docs/_build/html/index.html: check test
+	if [ ! -d docs/source/_static ]; then \
+	  mkdir docs/source/_static/; \
+	fi
 	$(MAKE) -C docs/ html
+docs-md: docs/_build/markdown/Home.md
+docs/_build/markdown/Home.md: check test
+	if [ ! -d docs/source/_static ]; then \
+	  mkdir docs/source/_static/; \
+	fi
+	$(MAKE) -C docs/ markdown
+	mv docs/_build/markdown/index.md docs/_build/markdown/Home.md
 
 # Prune the packages currently installed in the virtual environment down to the required
 # packages only. Pruning works in a roundabout way, where we first generate the wheels for

README.md

@@ -43,7 +43,7 @@ Comprehensive unit testing is enabled using [pytest](https://pytest.org/) combin
 
 ### Documentation
 
-Documentation is important, and [Sphinx](https://www.sphinx-doc.org/en/master/) is set up already to produce standard documentation for the package, assuming that code contains [docstrings with reStructuredText](https://www.python.org/dev/peps/pep-0287/) (see [below](#generating-documentation)).
+Documentation is important, and [Sphinx](https://www.sphinx-doc.org/en/master/) is already set up to produce standard documentation in HTML and Markdown formats for the package, assuming that code contains [docstrings with reStructuredText](https://www.python.org/dev/peps/pep-0287/); the generated Markdown documentation can also optionally be pushed to the repository’s Github Wiki (see [below](#generating-documentation)).
 
 ### Versioning and publishing
 
@@ -93,6 +93,7 @@ If you’d like to start your own Python project from scratch, you can either co
   - one PAT with `repo` scope (including _all_ of the `repo` permissions) for the secret named `REPO_ACCESS_TOKEN`; this secret is used by the [Release Action](https://github.com/jenstroeger/python-package-template/blob/main/.github/workflows/release.yaml) to push the release commit and attach assets to the generated [Github release](https://github.com/jenstroeger/python-package-template/releases).
   - one PAT with `public_repo`, `read:discussion`, `read:org`, and `read:repo_hook` scopes ([detailed docs](https://github.com/ossf/scorecard-action#authentication-with-pat)) for the secret named `SCORECARD_READ_TOKEN`; this secret is used by the [Scorecard Action](https://github.com/jenstroeger/python-package-template/blob/main/.github/workflows/scorecards-analysis.yaml) to analyze the code and add its results to your repository.
   - one PAT with `repo` scope for the secret named `DEPENDABOT_AUTOMERGE_TOKEN`; this secret is used by the [Dependabot Automerge Action](https://github.com/jenstroeger/python-package-template/blob/main/.github/workflows/dependabot-automerge.yaml) to comment on Dependabot PRs.
+- Create a Wiki and a first empty Wiki page for your new repository. Using the [Wiki Documentation](https://github.com/jenstroeger/python-package-template/blob/main/.github/workflows/_wiki-documentation.yaml) Action the repository’s Wiki will be automatically updated as part of publishing a new release.
 
 To develop your new package, first create a [virtual environment](https://docs.python.org/3/tutorial/venv.html) by either using the [Makefile](https://www.gnu.org/software/make/manual/make.html#toc-An-Introduction-to-Makefiles):
 
@@ -210,6 +211,8 @@ This example generates documentation in HTML, which can then be found here:
 open docs/_build/html/index.html
 ```
 
+In addition to the default HTML, Sphinx also generates Markdown documentation compatible with [Github Wiki](https://docs.github.com/en/communities/documenting-your-project-with-wikis), and the [Wiki Documentation](https://github.com/jenstroeger/python-package-template/blob/main/.github/workflows/_wiki-documentation.yaml) Action automatically updates the project repository’s Wiki.
+
 ## Versioning, publishing and changelog
 
 To enable automation for [semantic versioning](https://semver.org/), package publishing, and changelog generation it is important to use meaningful [conventional commit messages](https://www.conventionalcommits.org/)! This package template already has a built-in semantic release support enabled which is set up to take care of all three of these aspects — every time changes are merged into the `main` branch.

pyproject.toml

@@ -50,6 +50,7 @@ dev = [
 ]
 docs = [
     "sphinx >=5.1.1,<6.0.0",
+    "sphinxnotes-markdown-builder >=0.5.6,<1.0.0",
 ]
 hooks = [
     "pre-commit >=2.18.0,<2.22.0",