From 9a4fe9795e6fb50fea475c1b92927c7e78ac5a91 Mon Sep 17 00:00:00 2001 From: "Donal K. Fellows" Date: Sat, 27 Jun 2026 16:43:15 +0100 Subject: [PATCH 1/2] Allow wider range of Doxygen versions to be used This was previously limited to that supported by the Ubuntu release, but it turns out we can pull binaries direct from GitHub. --- .gitattributes | 1 + doxygen-to-pages/README.md | 11 +++++++++++ doxygen-to-pages/action.yml | 28 ++++++++++++++++++++++++---- doxygen-to-pages/download.bash | 24 ++++++++++++++++++++++++ 4 files changed, 60 insertions(+), 4 deletions(-) create mode 100755 doxygen-to-pages/download.bash diff --git a/.gitattributes b/.gitattributes index 3f26263..6156fec 100644 --- a/.gitattributes +++ b/.gitattributes @@ -13,3 +13,4 @@ # limitations under the License. *.yml linguist-detectable *.yaml linguist-detectable +*.bash text eol=lf diff --git a/doxygen-to-pages/README.md b/doxygen-to-pages/README.md index 872e79d..c9decc4 100644 --- a/doxygen-to-pages/README.md +++ b/doxygen-to-pages/README.md @@ -44,11 +44,22 @@ If that can't be determined, the environment variable will be set to `https://ex If this environment is not defined in the repository, a debugging artifact containing the Doxygen output will be attached to the workflow run summary page. +* `doxygen-version` + + The version of Doxygen to use. Defaults to `1.9.8`. **Optional.** + + Any version that has a binary release for Linux published on GitHub is supported. + See https://github.com/doxygen/doxygen/releases for the supported versions. + ## Outputs * `artifact_id` The ID of the artifact that was uploaded, if it is production-ready. The artifact is _not_ deployed by this action. +* `debug-artifact_id` + + The ID of the debug artifact that was uploaded, if it is _not_ a production-ready upload. Note that debug artifacts are easier to extract and view than main artifacts. + * `deploy-ready` Whether a deployment is possible from what was uploaded. Either `true` or `false`, as strings. diff --git a/doxygen-to-pages/action.yml b/doxygen-to-pages/action.yml index c38db19..34d0b8e 100644 --- a/doxygen-to-pages/action.yml +++ b/doxygen-to-pages/action.yml @@ -33,10 +33,19 @@ inputs: description: > The environment that will be published to. default: github-pages + doxygen-version: + description: > + The version of Doxygen to use. + Any version that has a binary release for Linux published on GitHub is supported. + See https://github.com/doxygen/doxygen/releases + default: "1.9.8" outputs: artifact_id: description: The ID of the artifact that was uploaded. value: ${{ steps.upload.outputs.artifact_id || '' }} + debug-artifact_id: + description: The ID of the debug artifact that was uploaded. + value: ${{ steps.debug-upload.outputs.artifact_id || '' }} deploy-ready: description: Whether a deployment is possible from what was uploaded. value: ${{ steps.upload.outcome == 'success' }} @@ -45,18 +54,28 @@ runs: steps: - name: Check for Environment id: env-chk - uses: UoMResearchIT/actions/list-environments@d1daa552b595b77a4628d28de138db571e91ab87 # v1.2.5 + uses: UoMResearchIT/actions/list-environments@b747e3097a2cb9d927b63e2bb83fbf6e75716a53 # v1.2.6 with: has-env: ${{ inputs.publish-environment }} - name: Setup Pages if: steps.env-chk.outputs.env-present == 'true' id: setup uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0 - - name: Run Doxygen - uses: mattnotmitt/doxygen-action@b84fe17600245bb5db3d6c247cc274ea98c15a3b # v1.12.0 + - name: Install Dependencies + uses: UoMResearchIT/actions/apt-get-install@b747e3097a2cb9d927b63e2bb83fbf6e75716a53 # v1.2.6 with: - working-directory: ${{ inputs.working-directory }} + packages: wget graphviz + - name: Install Doxygen v${{ inputs.doxygen-version }} + shell: bash + run: exec $GITHUB_ACTION_PATH/download.bash + env: + DOXY_VER: ${{ inputs.doxygen-version }} + - name: Run Doxygen + shell: bash + run: "${DOXY_PATH}/doxygen" + working-directory: ${{ inputs.working-directory }} env: + DOXY_PATH: ${{ github.workspace }}/doxygen-${{ inputs.doxygen-version }}/bin SITE_URL: ${{ steps.setup.outputs.base_url || 'https://example.org/' }} - name: Upload Artifact if: steps.env-chk.outputs.env-present == 'true' @@ -66,6 +85,7 @@ runs: path: ${{ inputs.working-directory }}/html - name: Upload Debug Artifact if: steps.env-chk.outputs.env-present != 'true' + id: debug-upload uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1 with: name: Doxygen HTML Build diff --git a/doxygen-to-pages/download.bash b/doxygen-to-pages/download.bash new file mode 100755 index 0000000..a1954c0 --- /dev/null +++ b/doxygen-to-pages/download.bash @@ -0,0 +1,24 @@ +#!/usr/bin/env bash + +# Copyright (c) 2026 The University of Manchester +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# https://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +set -e + +rel_name="Release_$(echo "$DOXY_VER" | tr '.' '_')" +url="https://github.com/doxygen/doxygen/releases/download/${rel_name}/doxygen-${DOXY_VER}.linux.bin.tar.gz" +echo "Download from: ${url}" +echo "" + +wget -nv -O - "$url" | tar -xzf - From c96facd8238736edecc1215d01e37cec6f3a8873 Mon Sep 17 00:00:00 2001 From: "Donal K. Fellows" Date: Mon, 29 Jun 2026 09:14:49 +0100 Subject: [PATCH 2/2] Add a problem matcher Doxygen errors tend to get lost as warnings, so it's useful to make them more visible. Problem matchers are deep Github (and VSCode) voodoo. --- doxygen-to-pages/action.yml | 4 +++- doxygen-to-pages/doxygen-problem-matcher.json | 16 ++++++++++++++++ 2 files changed, 19 insertions(+), 1 deletion(-) create mode 100644 doxygen-to-pages/doxygen-problem-matcher.json diff --git a/doxygen-to-pages/action.yml b/doxygen-to-pages/action.yml index 34d0b8e..b578f0d 100644 --- a/doxygen-to-pages/action.yml +++ b/doxygen-to-pages/action.yml @@ -72,7 +72,9 @@ runs: DOXY_VER: ${{ inputs.doxygen-version }} - name: Run Doxygen shell: bash - run: "${DOXY_PATH}/doxygen" + run: | + echo "::add-matcher::${GITHUB_ACTION_PATH}/doxygen-problem-matcher.json" + "${DOXY_PATH}/doxygen" working-directory: ${{ inputs.working-directory }} env: DOXY_PATH: ${{ github.workspace }}/doxygen-${{ inputs.doxygen-version }}/bin diff --git a/doxygen-to-pages/doxygen-problem-matcher.json b/doxygen-to-pages/doxygen-problem-matcher.json new file mode 100644 index 0000000..6e98a74 --- /dev/null +++ b/doxygen-to-pages/doxygen-problem-matcher.json @@ -0,0 +1,16 @@ +{ + "problemMatcher": [ + { + "owner": "doxygen", + "pattern": [ + { + "regexp": "^.*\/(.+):([0-9]+): ([a-zA-Z]+): (.+)$", + "file": 1, + "line": 2, + "severity": 3, + "message": 4 + } + ] + } + ] +}