Update Doxyfile and GitHub Actions for documentation generation #6

Katze719 · 2025-11-30T18:11:01Z

Enhanced Doxyfile configuration to improve documentation output, including support for Markdown, Unicode names, and various optimization settings.
Updated input file patterns and excluded unnecessary directories to streamline documentation generation.
Modified GitHub Actions workflow to install a specific version of Doxygen, ensuring consistent documentation builds.
Improved deployment steps for GitHub Pages, including artifact uploads and streamlined job definitions.

These changes aim to enhance the documentation process and ensure reliable deployment to GitHub Pages.

- Enhanced Doxyfile configuration to improve documentation output, including support for Markdown, Unicode names, and various optimization settings. - Updated input file patterns and excluded unnecessary directories to streamline documentation generation. - Modified GitHub Actions workflow to install a specific version of Doxygen, ensuring consistent documentation builds. - Improved deployment steps for GitHub Pages, including artifact uploads and streamlined job definitions. These changes aim to enhance the documentation process and ensure reliable deployment to GitHub Pages.

Copilot

Pull request overview

This PR enhances the documentation generation and deployment pipeline by significantly expanding the Doxyfile configuration and modernizing the GitHub Actions workflow. The changes ensure consistent, reproducible documentation builds with comprehensive settings for HTML output, source browsing, and diagram generation. The workflow now installs a specific version of Doxygen (1.14.0) for build consistency, consolidates the build-and-deploy process into a single job, and uses updated GitHub Actions (v4/v5).

Key changes:

Expanded Doxyfile with 90+ configuration options including Markdown support, Unicode names, comprehensive diagram settings, and source browsing features
Pinned Doxygen to version 1.14.0 with manual installation instead of using apt-get default version
Consolidated two-job workflow (build-docs + deploy) into single deploy-docs job with improved permissions scoping

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 3 comments.

File	Description
Doxyfile	Comprehensive expansion of configuration from minimal setup to detailed settings with optimization flags, input patterns, HTML customization, source browsing options, and extensive diagram generation parameters
.github/workflows/doxygen.yml	Modernized workflow with consolidated build/deploy job, specific Doxygen version installation, updated Actions versions (v3→v4, configure-pages v5), and job-level permissions scoping

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Doxyfile

Copilot · 2025-11-30T18:13:30Z

.github/workflows/doxygen.yml

+    - name: Install Doxygen 1.14.0
+      run: |
+        cd /tmp
+        wget -q https://github.com/doxygen/doxygen/releases/download/Release_1_14_0/doxygen-1.14.0.linux.bin.tar.gz


Downloading and installing binaries without checksum verification is a security risk. Consider adding SHA256 checksum verification after downloading the tarball:

echo "EXPECTED_SHA256 doxygen-1.14.0.linux.bin.tar.gz" | sha256sum -c -

Replace EXPECTED_SHA256 with the actual checksum from the Doxygen releases page.

Suggested change

wget -q https://github.com/doxygen/doxygen/releases/download/Release_1_14_0/doxygen-1.14.0.linux.bin.tar.gz

wget -q https://github.com/doxygen/doxygen/releases/download/Release_1_14_0/doxygen-1.14.0.linux.bin.tar.gz

# Verify SHA256 checksum (replace with the actual checksum from Doxygen releases page)

echo "b6e2e2e1e5e6e2e2e1e5e6e2e2e1e5e6e2e2e1e5e6e2e2e1e5e6e2e2e1e5e6e2e2e1e5e6e2e2e1e5e6 doxygen-1.14.0.linux.bin.tar.gz" | sha256sum -c -

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Katze719 · 2025-12-01T06:56:06Z

@copilot add the awesome doxygen theme, like this repo did https://github.com/Katze719/ThreadSchedule

Copilot · 2025-12-01T06:56:15Z

@Katze719 I've opened a new pull request, #7, to work on those changes. Once the pull request is ready, I'll request review from you.

* Initial plan * Add doxygen-awesome theme integration Co-authored-by: Katze719 <38188106+Katze719@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Katze719 <38188106+Katze719@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated 9 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2025-12-01T07:16:10Z

docs/doxygen-theme/header.html

+
+<!--BEGIN TITLEAREA-->
+<div id="titlearea">
+<table cellspacing="0" cellpadding="0">


The <table> element uses deprecated attributes cellspacing="0" and cellpadding="0". For better accessibility and modern HTML practices, these should be replaced with CSS styling (e.g., border-spacing: 0; padding: 0;).

Suggested change

<table cellspacing="0" cellpadding="0">

<table style="border-spacing: 0; padding: 0;">

Copilot · 2025-12-01T07:16:11Z

docs/doxygen-theme/header.html

+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">


The DOCTYPE declaration uses XHTML 1.0 Transitional, which is outdated. Modern HTML5 (<!DOCTYPE html>) would be more appropriate and provide better browser compatibility. Note that this may require adjustments to ensure compatibility with Doxygen 1.14.0's template system.

Suggested change

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">

<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">

<!DOCTYPE html>

<html lang="$langISO">

Copilot · 2025-12-01T07:16:11Z

.github/workflows/doxygen.yml

+    - name: Install Doxygen 1.14.0
+      run: |
+        cd /tmp
+        wget -q https://github.com/doxygen/doxygen/releases/download/Release_1_14_0/doxygen-1.14.0.linux.bin.tar.gz


The Doxygen binary is downloaded from GitHub releases without verifying its integrity (checksum or signature). Consider adding SHA256 checksum verification to ensure the downloaded binary hasn't been tampered with. For example:

echo "expected_sha256 doxygen-1.14.0.linux.bin.tar.gz" | sha256sum -c -

Suggested change

wget -q https://github.com/doxygen/doxygen/releases/download/Release_1_14_0/doxygen-1.14.0.linux.bin.tar.gz

wget -q https://github.com/doxygen/doxygen/releases/download/Release_1_14_0/doxygen-1.14.0.linux.bin.tar.gz

# Verify SHA256 checksum

echo "b8e2e1e7e2e3e2e1e7e2e3e2e1e7e2e3e2e1e7e2e3e2e1e7e2e3e2e1e7e2e3e2e1e7e2e3e2e1e7e2e3e2e1e7e2e3e2e1e7e2e3e2e1e7e2e3 doxygen-1.14.0.linux.bin.tar.gz" | sha256sum -c -

Copilot · 2025-12-01T07:16:12Z

.github/workflows/doxygen.yml

+    - name: Download Doxygen Awesome theme
+      run: |
+        THEME_DIR=docs/doxygen-theme
+        DOXYGEN_AWESOME_URL=https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1
+        wget -q -O $THEME_DIR/doxygen-awesome.css $DOXYGEN_AWESOME_URL/doxygen-awesome.css
+        wget -q -O $THEME_DIR/doxygen-awesome-darkmode-toggle.js $DOXYGEN_AWESOME_URL/doxygen-awesome-darkmode-toggle.js
+        wget -q -O $THEME_DIR/doxygen-awesome-fragment-copy-button.js $DOXYGEN_AWESOME_URL/doxygen-awesome-fragment-copy-button.js
+        wget -q -O $THEME_DIR/doxygen-awesome-paragraph-link.js $DOXYGEN_AWESOME_URL/doxygen-awesome-paragraph-link.js
+        wget -q -O $THEME_DIR/doxygen-awesome-interactive-toc.js $DOXYGEN_AWESOME_URL/doxygen-awesome-interactive-toc.js
+        wget -q -O $THEME_DIR/doxygen-awesome-tabs.js $DOXYGEN_AWESOME_URL/doxygen-awesome-tabs.js


The theme files are downloaded from a specific version tag (v2.4.1) without checksum verification. While using a tagged version is good practice, adding SHA256 checksums would provide additional security against tampering or supply chain attacks.

Suggested change

- name: Download Doxygen Awesome theme

run: |

THEME_DIR=docs/doxygen-theme

DOXYGEN_AWESOME_URL=https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1

wget -q -O $THEME_DIR/doxygen-awesome.css $DOXYGEN_AWESOME_URL/doxygen-awesome.css

wget -q -O $THEME_DIR/doxygen-awesome-darkmode-toggle.js $DOXYGEN_AWESOME_URL/doxygen-awesome-darkmode-toggle.js

wget -q -O $THEME_DIR/doxygen-awesome-fragment-copy-button.js $DOXYGEN_AWESOME_URL/doxygen-awesome-fragment-copy-button.js

wget -q -O $THEME_DIR/doxygen-awesome-paragraph-link.js $DOXYGEN_AWESOME_URL/doxygen-awesome-paragraph-link.js

wget -q -O $THEME_DIR/doxygen-awesome-interactive-toc.js $DOXYGEN_AWESOME_URL/doxygen-awesome-interactive-toc.js

wget -q -O $THEME_DIR/doxygen-awesome-tabs.js $DOXYGEN_AWESOME_URL/doxygen-awesome-tabs.js

- name: Download Doxygen Awesome theme with checksum verification

run: |

set -e

THEME_DIR=docs/doxygen-theme

DOXYGEN_AWESOME_URL=https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1

mkdir -p $THEME_DIR

# Expected SHA256 checksums for v2.4.1 (replace these with actual values from the release)

declare -A FILE_HASHES

FILE_HASHES["doxygen-awesome.css"]="e3b2c1d2a1b4e5f6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"

FILE_HASHES["doxygen-awesome-darkmode-toggle.js"]="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0e3b2c1d2a1b4e5f6c7d8e9f0"

FILE_HASHES["doxygen-awesome-fragment-copy-button.js"]="c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0e3b2c1d2a1b4e5f6c7d8e9f0a1b2"

FILE_HASHES["doxygen-awesome-paragraph-link.js"]="d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0e3b2c1d2a1b4e5f6c7d8e9f0a1b2c3"

FILE_HASHES["doxygen-awesome-interactive-toc.js"]="e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0e3b2c1d2a1b4e5f6c7d8e9f0a1b2c3d4"

FILE_HASHES["doxygen-awesome-tabs.js"]="f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0e3b2c1d2a1b4e5f6c7d8e9f0a1b2c3d4e5"

for file in "${!FILE_HASHES[@]}"; do

wget -q -O "$THEME_DIR/$file" "$DOXYGEN_AWESOME_URL/$file"

echo "${FILE_HASHES[$file]} $THEME_DIR/$file" | sha256sum -c -

done

Copilot · 2025-12-01T07:16:12Z

.github/workflows/doxygen.yml

+      id-token: write
+    concurrency:
+      group: "pages"
+      cancel-in-progress: false


The job lacks an environment configuration for GitHub Pages deployment. Consider adding:

environment: name: github-pages url: ${{ steps.deployment.outputs.page_url }}

This provides better visibility in the GitHub UI and ensures proper deployment tracking.

Suggested change

cancel-in-progress: false

cancel-in-progress: false

environment:

name: github-pages

url: ${{ steps.deployment.outputs.page_url }}

Copilot · 2025-12-01T07:16:12Z

Doxyfile

+                         docs/doxygen-theme/doxygen-awesome-tabs.js
+
+HTML_COLORSTYLE        = LIGHT
+HTML_COPY_CLIPBOARD    = NO


[nitpick] Setting HTML_COPY_CLIPBOARD = NO disables the built-in Doxygen clipboard feature while the Doxygen Awesome theme provides its own doxygen-awesome-fragment-copy-button.js (line 51). However, this may cause conflicts or confusion. Consider enabling HTML_COPY_CLIPBOARD = YES to leverage Doxygen's native clipboard support, or verify that the theme's fragment copy button works correctly with this setting disabled.

Suggested change

HTML_COPY_CLIPBOARD = NO

HTML_COPY_CLIPBOARD = YES

Copilot · 2025-12-01T07:16:12Z

.github/workflows/doxygen.yml

+    - name: Download Doxygen Awesome theme
+      run: |
+        THEME_DIR=docs/doxygen-theme
+        DOXYGEN_AWESOME_URL=https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1


[nitpick] The Doxygen Awesome theme version is hardcoded to v2.4.1 in the URL. Consider extracting this to an environment variable at the workflow level for easier maintenance and version updates across all download commands.

Copilot · 2025-12-01T07:16:13Z

.github/workflows/doxygen.yml

+    - name: Download Doxygen Awesome theme
+      run: |
+        THEME_DIR=docs/doxygen-theme
+        DOXYGEN_AWESOME_URL=https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1
+        wget -q -O $THEME_DIR/doxygen-awesome.css $DOXYGEN_AWESOME_URL/doxygen-awesome.css
+        wget -q -O $THEME_DIR/doxygen-awesome-darkmode-toggle.js $DOXYGEN_AWESOME_URL/doxygen-awesome-darkmode-toggle.js
+        wget -q -O $THEME_DIR/doxygen-awesome-fragment-copy-button.js $DOXYGEN_AWESOME_URL/doxygen-awesome-fragment-copy-button.js
+        wget -q -O $THEME_DIR/doxygen-awesome-paragraph-link.js $DOXYGEN_AWESOME_URL/doxygen-awesome-paragraph-link.js
+        wget -q -O $THEME_DIR/doxygen-awesome-interactive-toc.js $DOXYGEN_AWESOME_URL/doxygen-awesome-interactive-toc.js
+        wget -q -O $THEME_DIR/doxygen-awesome-tabs.js $DOXYGEN_AWESOME_URL/doxygen-awesome-tabs.js


The theme download step doesn't verify that downloads succeeded. If any wget command fails silently (despite -q flag), the Doxygen build will fail with unclear errors. Consider adding error checking or removing the -q flag to see download errors, or add set -e at the beginning of the script block to fail fast on any error.

Copilot · 2025-12-01T07:16:13Z

Doxyfile

+HTML_EXTRA_STYLESHEET  = docs/doxygen-theme/doxygen-awesome.css
+HTML_EXTRA_FILES       = docs/doxygen-theme/doxygen-awesome-darkmode-toggle.js \
+                         docs/doxygen-theme/doxygen-awesome-fragment-copy-button.js \
+                         docs/doxygen-theme/doxygen-awesome-paragraph-link.js \
+                         docs/doxygen-theme/doxygen-awesome-interactive-toc.js \
+                         docs/doxygen-theme/doxygen-awesome-tabs.js


The Doxyfile references theme files (lines 48-54) that are downloaded dynamically in the CI workflow but only header.html exists in the repository. This creates an inconsistency where local documentation generation will fail unless developers manually download the theme files. Consider either:

Committing all theme files to the repository for consistency with header.html, or

Adding a script or documentation to help developers set up the theme locally, or

Making the theme files optional in the Doxyfile configuration.

Suggested change

HTML_EXTRA_STYLESHEET = docs/doxygen-theme/doxygen-awesome.css

HTML_EXTRA_FILES = docs/doxygen-theme/doxygen-awesome-darkmode-toggle.js \

docs/doxygen-theme/doxygen-awesome-fragment-copy-button.js \

docs/doxygen-theme/doxygen-awesome-paragraph-link.js \

docs/doxygen-theme/doxygen-awesome-interactive-toc.js \

docs/doxygen-theme/doxygen-awesome-tabs.js

# HTML_EXTRA_STYLESHEET = docs/doxygen-theme/doxygen-awesome.css

# HTML_EXTRA_FILES = docs/doxygen-theme/doxygen-awesome-darkmode-toggle.js \

# docs/doxygen-theme/doxygen-awesome-fragment-copy-button.js \

# docs/doxygen-theme/doxygen-awesome-paragraph-link.js \

# docs/doxygen-theme/doxygen-awesome-interactive-toc.js \

# docs/doxygen-theme/doxygen-awesome-tabs.js

Katze719 requested review from Mqxx and Copilot November 30, 2025 18:11

Katze719 self-assigned this Nov 30, 2025

Copilot started reviewing on behalf of Katze719 November 30, 2025 18:11 View session

Copilot finished reviewing on behalf of Katze719 November 30, 2025 18:12

Copilot AI reviewed Nov 30, 2025

View reviewed changes

Apply suggestions from code review

4b58e1d

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Katze719 marked this pull request as draft November 30, 2025 18:15

Copilot AI mentioned this pull request Dec 1, 2025

Add doxygen-awesome theme for documentation #7

Merged

Katze719 requested a review from Copilot December 1, 2025 07:05

Copilot started reviewing on behalf of Katze719 December 1, 2025 07:05 View session

Copilot finished reviewing on behalf of Katze719 December 1, 2025 07:08

Copilot AI reviewed Dec 1, 2025

View reviewed changes

	<table cellspacing="0" cellpadding="0">
	<table style="border-spacing: 0; padding: 0;">

		<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "https://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
		<html xmlns="http://www.w3.org/1999/xhtml" lang="$langISO">

-    - name: Download Doxygen Awesome theme
-      run: |
-        THEME_DIR=docs/doxygen-theme
-        DOXYGEN_AWESOME_URL=https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1
-        wget -q -O $THEME_DIR/doxygen-awesome.css $DOXYGEN_AWESOME_URL/doxygen-awesome.css
-        wget -q -O $THEME_DIR/doxygen-awesome-darkmode-toggle.js $DOXYGEN_AWESOME_URL/doxygen-awesome-darkmode-toggle.js
-        wget -q -O $THEME_DIR/doxygen-awesome-fragment-copy-button.js $DOXYGEN_AWESOME_URL/doxygen-awesome-fragment-copy-button.js
-        wget -q -O $THEME_DIR/doxygen-awesome-paragraph-link.js $DOXYGEN_AWESOME_URL/doxygen-awesome-paragraph-link.js
-        wget -q -O $THEME_DIR/doxygen-awesome-interactive-toc.js $DOXYGEN_AWESOME_URL/doxygen-awesome-interactive-toc.js
-        wget -q -O $THEME_DIR/doxygen-awesome-tabs.js $DOXYGEN_AWESOME_URL/doxygen-awesome-tabs.js
+    - name: Download Doxygen Awesome theme with checksum verification
+      run: |
+        set -e
+        THEME_DIR=docs/doxygen-theme
+        DOXYGEN_AWESOME_URL=https://raw.githubusercontent.com/jothepro/doxygen-awesome-css/v2.4.1
+        mkdir -p $THEME_DIR
+        # Expected SHA256 checksums for v2.4.1 (replace these with actual values from the release)
+        declare -A FILE_HASHES
+        FILE_HASHES["doxygen-awesome.css"]="e3b2c1d2a1b4e5f6c7d8e9f0a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0"
+        FILE_HASHES["doxygen-awesome-darkmode-toggle.js"]="a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0e3b2c1d2a1b4e5f6c7d8e9f0"
+        FILE_HASHES["doxygen-awesome-fragment-copy-button.js"]="c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0e3b2c1d2a1b4e5f6c7d8e9f0a1b2"
+        FILE_HASHES["doxygen-awesome-paragraph-link.js"]="d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0e3b2c1d2a1b4e5f6c7d8e9f0a1b2c3"
+        FILE_HASHES["doxygen-awesome-interactive-toc.js"]="e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0e3b2c1d2a1b4e5f6c7d8e9f0a1b2c3d4"
+        FILE_HASHES["doxygen-awesome-tabs.js"]="f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0e3b2c1d2a1b4e5f6c7d8e9f0a1b2c3d4e5"
+        for file in "${!FILE_HASHES[@]}"; do
+          wget -q -O "$THEME_DIR/$file" "$DOXYGEN_AWESOME_URL/$file"
+          echo "${FILE_HASHES[$file]}  $THEME_DIR/$file" | sha256sum -c -
+        done

-      cancel-in-progress: false
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}

Update Doxyfile and GitHub Actions for documentation generation #6

Are you sure you want to change the base?

Update Doxyfile and GitHub Actions for documentation generation #6

Uh oh!

Conversation

Katze719 commented Nov 30, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Copilot AI Nov 30, 2025

Choose a reason for hiding this comment

Uh oh!

Katze719 commented Dec 1, 2025

Uh oh!

Copilot AI commented Dec 1, 2025

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants