From 99554b454378f59460c5369770c40fbd9651eede Mon Sep 17 00:00:00 2001 From: Katze719 Date: Sun, 30 Nov 2025 19:10:33 +0100 Subject: [PATCH 1/3] Update Doxyfile and GitHub Actions for documentation generation - 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. --- .github/workflows/doxygen.yml | 66 ++++++++++++++-------------- Doxyfile | 81 +++++++++++++++++++++++++++-------- 2 files changed, 98 insertions(+), 49 deletions(-) diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index bf0be46..1ccb31f 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -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 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 + 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 diff --git a/Doxyfile b/Doxyfile index 7dd8112..10b7b11 100644 --- a/Doxyfile +++ b/Doxyfile @@ -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" 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 +PAGE_OUTLINE_PANEL = NO +FULL_SIDEBAR = NO +GENERATE_TREEVIEW = YES +DISABLE_INDEX = NO +ALPHABETICAL_INDEX = YES +GENERATE_DEPRECATEDLIST= YES + +# 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 From 4b58e1dc69368aecc72e6f6dbccbfc493505dad6 Mon Sep 17 00:00:00 2001 From: Katze719 <38188106+Katze719@users.noreply.github.com> Date: Sun, 30 Nov 2025 19:14:59 +0100 Subject: [PATCH 2/3] Apply suggestions from code review Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- Doxyfile | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doxyfile b/Doxyfile index 10b7b11..f915660 100644 --- a/Doxyfile +++ b/Doxyfile @@ -5,7 +5,7 @@ # Project related -------------------------------------------------------- PROJECT_NAME = "cpp-core" PROJECT_NUMBER = "1.0" -PROJECT_BRIEF = "Header-only C++ helper library" +PROJECT_BRIEF = "Header-only API definitions for cross-platform serial communication" OUTPUT_DIRECTORY = docs/html CREATE_SUBDIRS = NO ALLOW_UNICODE_NAMES = YES @@ -51,7 +51,7 @@ FULL_SIDEBAR = NO GENERATE_TREEVIEW = YES DISABLE_INDEX = NO ALPHABETICAL_INDEX = YES -GENERATE_DEPRECATEDLIST= YES +GENERATE_DEPRECATEDLIST = YES # Source browsing SOURCE_BROWSER = YES From 94938f8bc1fb1d701529d40ff889924fbc25eece Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Mon, 1 Dec 2025 08:04:29 +0100 Subject: [PATCH 3/3] Add doxygen-awesome theme for documentation (#7) * 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> --- .github/workflows/doxygen.yml | 12 +++++ Doxyfile | 9 ++++ docs/doxygen-theme/header.html | 89 ++++++++++++++++++++++++++++++++++ 3 files changed, 110 insertions(+) create mode 100644 docs/doxygen-theme/header.html diff --git a/.github/workflows/doxygen.yml b/.github/workflows/doxygen.yml index 1ccb31f..210445a 100644 --- a/.github/workflows/doxygen.yml +++ b/.github/workflows/doxygen.yml @@ -6,6 +6,7 @@ on: paths: - 'include/**' - 'Doxyfile' + - 'docs/doxygen-theme/**' - '.github/workflows/doxygen.yml' - 'README.md' @@ -35,6 +36,17 @@ jobs: sudo apt-get update sudo apt-get install -y graphviz + - 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: Generate documentation run: | doxygen Doxyfile diff --git a/Doxyfile b/Doxyfile index f915660..379029a 100644 --- a/Doxyfile +++ b/Doxyfile @@ -44,6 +44,15 @@ HTML_OUTPUT = . GENERATE_LATEX = NO GENERATE_XML = NO +# Doxygen Awesome theme integration +HTML_HEADER = docs/doxygen-theme/header.html +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_COLORSTYLE = LIGHT HTML_COPY_CLIPBOARD = NO PAGE_OUTLINE_PANEL = NO diff --git a/docs/doxygen-theme/header.html b/docs/doxygen-theme/header.html new file mode 100644 index 0000000..8e5601c --- /dev/null +++ b/docs/doxygen-theme/header.html @@ -0,0 +1,89 @@ + + + + + + + + +$projectname: $title +$title + + + + + + + + + + + + +$treeview +$search +$mathjax +$darkmode + +$extrastylesheet + + + + + + + + + + +
+ + +
+ + +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+
$projectname $projectnumber +
+
$projectbrief
+ 		+
$projectbrief
+ 		$searchbox
$searchbox
+
+ +