Skip to content

Update Doxyfile and GitHub Actions for documentation generation #6

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
Katze719 wants to merge 3 commits into
base: main
Choose a base branch
from
Draft

Update Doxyfile and GitHub Actions for documentation generation #6

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
99554b4
Update Doxyfile and GitHub Actions for documentation generation
Katze719 Nov 30, 2025
4b58e1d
Apply suggestions from code review
Katze719 Nov 30, 2025
94938f8
Add doxygen-awesome theme for documentation (#7)
Copilot Dec 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
66 changes: 35 additions & 31 deletions .github/workflows/doxygen.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,42 +7,46 @@ on:
- 'include/**'
- 'Doxyfile'
- '.github/workflows/doxygen.yml'
workflow_dispatch:

# Required for GitHub Pages deployment
permissions:
contents: write
pages: write
id-token: write
- 'README.md'

jobs:
build-docs:
# Build and deploy Doxygen to GitHub Pages
deploy-docs:
name: Build & Deploy Doxygen
runs-on: ubuntu-latest
name: 'Build Doxygen HTML'
permissions:
contents: read
pages: write
id-token: write
concurrency:
group: "pages"
cancel-in-progress: false
Copy link

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
steps:
- name: Checkout
uses: actions/checkout@v3
- name: Checkout code
uses: actions/checkout@v4

- name: Install Doxygen + Graphviz
run: |
sudo apt-get update -qq
sudo apt-get install -y doxygen graphviz
- 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
Copy link

Copilot AI Nov 30, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 -

Copilot uses AI. Check for mistakes.
Copy link

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 uses AI. Check for mistakes.
tar -xzf doxygen-1.14.0.linux.bin.tar.gz
sudo cp doxygen-1.14.0/bin/doxygen /usr/local/bin/
doxygen --version
sudo apt-get update
sudo apt-get install -y graphviz

- name: Generate documentation
run: |
doxygen -v
doxygen Doxyfile
- name: Generate documentation
run: |
doxygen Doxyfile

- name: Upload Pages artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/html
- name: Setup Pages
uses: actions/configure-pages@v5

deploy:
needs: build-docs
runs-on: ubuntu-latest
name: 'Deploy to GitHub Pages'
steps:
- name: Deploy
id: deployment
uses: actions/deploy-pages@v4
- name: Upload artifact
uses: actions/upload-pages-artifact@v3
with:
path: docs/html

- name: Deploy to GitHub Pages
id: deployment
uses: actions/deploy-pages@v4
81 changes: 63 additions & 18 deletions Doxyfile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,42 +4,87 @@

# Project related --------------------------------------------------------
PROJECT_NAME = "cpp-core"
PROJECT_BRIEF = "Header-only C++ helper library"
PROJECT_NUMBER = "1.0"
PROJECT_BRIEF = "Header-only C++ helper library"
Comment thread
Katze719 marked this conversation as resolved.
Outdated
OUTPUT_DIRECTORY = docs/html
CREATE_SUBDIRS = NO
ALLOW_UNICODE_NAMES = YES
OPTIMIZE_OUTPUT_FOR_C = NO
OPTIMIZE_OUTPUT_JAVA = NO
OPTIMIZE_FOR_FORTRAN = NO
OPTIMIZE_OUTPUT_VHDL = NO
OPTIMIZE_OUTPUT_SLICE = NO
MARKDOWN_SUPPORT = YES
AUTOLINK_SUPPORT = YES
USE_MDFILE_AS_MAINPAGE = README.md

FULL_PATH_NAMES = NO
STRIP_FROM_PATH = include

# Source files -----------------------------------------------------------
INPUT = README.md include LICENSE
FILE_PATTERNS = *.h *.hpp *.md
RECURSIVE = YES
EXCLUDE_PATTERNS = */build/* */.git/* */install/*

# Build options ----------------------------------------------------------
EXTRACT_ALL = YES
EXTRACT_PRIVATE = YES
EXTRACT_STATIC = YES
EXTRACT_LOCAL_CLASSES = YES
EXTRACT_ANON_NSPACES = YES

# Source files -----------------------------------------------------------
INPUT = include README.md LICENSE
FILE_PATTERNS = *.h *.hpp *.md
RECURSIVE = YES
QUIET = YES
WARN_IF_UNDOCUMENTED = NO
WARN_AS_ERROR = NO

# HTML output ------------------------------------------------------------
GENERATE_HTML = YES
HTML_OUTPUT = .
HTML_COLORSTYLE_HUE = 220
HTML_COLORSTYLE_SAT = 100
HTML_COLORSTYLE_GAMMA = 80

# Disable unwanted output -----------------------------------------------
GENERATE_LATEX = NO
GENERATE_MAN = NO
GENERATE_RTF = NO
GENERATE_XML = NO

HTML_COLORSTYLE = LIGHT
HTML_COPY_CLIPBOARD = NO
Copy link

Copilot AI Dec 1, 2025

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[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 uses AI. Check for mistakes.
PAGE_OUTLINE_PANEL = NO
FULL_SIDEBAR = NO
GENERATE_TREEVIEW = YES
DISABLE_INDEX = NO
ALPHABETICAL_INDEX = YES
GENERATE_DEPRECATEDLIST= YES
Comment thread
Katze719 marked this conversation as resolved.
Outdated

# Source browsing
SOURCE_BROWSER = YES
INLINE_SOURCES = NO
STRIP_CODE_COMMENTS = YES
REFERENCED_BY_RELATION = YES
REFERENCES_RELATION = YES
VERBATIM_HEADERS = YES
SHOW_INCLUDE_FILES = YES
SHOW_GROUPED_MEMB_INC = NO

# Diagrams --------------------------------------------------------------
HAVE_DOT = YES
DOT_IMAGE_FORMAT = svg
DOT_NUM_THREADS = 0
CLASS_GRAPH = YES
COLLABORATION_GRAPH = YES
GROUP_GRAPHS = YES
UML_LOOK = NO
UML_LIMIT_NUM_FIELDS = 10
DOT_UML_DETAILS = NO
DOT_WRAP_THRESHOLD = 17
TEMPLATE_RELATIONS = YES
INCLUDE_GRAPH = YES
INCLUDED_BY_GRAPH = YES
CALL_GRAPH = YES
CALLER_GRAPH = YES

# Misc ------------------------------------------------------------------
FULL_PATH_NAMES = NO
STRIP_FROM_PATH = include
GENERATE_TREEVIEW = YES
GRAPHICAL_HIERARCHY = YES
DIRECTORY_GRAPH = YES
DIR_GRAPH_MAX_DEPTH = 1
DOT_IMAGE_FORMAT = svg
INTERACTIVE_SVG = YES
DOT_GRAPH_MAX_NODES = 50
MAX_DOT_GRAPH_DEPTH = 0
DOT_MULTI_TARGETS = YES
GENERATE_LEGEND = YES
DOT_CLEANUP = YES