From ed1b99ba14b16c23582051e9fb8e01a78853898d Mon Sep 17 00:00:00 2001
From: rfprod <zoidenmacht@zoho.com>
Date: Thu, 8 Oct 2026 10:47:14 +0400
Subject: [PATCH] feat(ci): add github pages workflow for cpp documentation

- [x] implement a workflow for automated documentation generation;
- [x] configure `Doxygen` to generate `XML` from `C++` source files;
- [x] set up `Sphinx` with `breathe` and `sphinx-rtd-theme` extensions;
- [x] add documentation deployment to github pages on main push;
- [x] add python dependencies for Sphinx and Breathe integration;
---
 .github/workflows/gh-pages.yml | 93 ++++++++++++++++++++++++++++++++++
 docs/conf.py                   | 13 +++++
 docs/index.rst                 |  8 +++
 docs/requirements.txt          |  3 ++
 4 files changed, 117 insertions(+)
 create mode 100644 .github/workflows/gh-pages.yml
 create mode 100644 docs/conf.py
 create mode 100644 docs/index.rst
 create mode 100644 docs/requirements.txt

diff --git a/.github/workflows/gh-pages.yml b/.github/workflows/gh-pages.yml
new file mode 100644
index 0000000..5819c0a
--- /dev/null
+++ b/.github/workflows/gh-pages.yml
@@ -0,0 +1,93 @@
+name: gh-pages
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: read
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v7
+
+      - name: Install Doxygen and Graphviz
+        run: |
+          sudo apt-get update
+          sudo apt-get install --yes --no-install-recommends doxygen graphviz
+
+      - name: Build documentation
+        run: |
+          python3 -m venv .venv
+          source .venv/bin/activate
+          pip install -U pip
+          pip install -r docs/requirements.txt
+
+          mkdir -p build
+          cat > build/Doxyfile <<'EOF'
+          PROJECT_NAME           = cpp-workspace
+          OUTPUT_DIRECTORY       = build/doxygen
+          INPUT                  = src
+          RECURSIVE              = YES
+          FILE_PATTERNS          = *.h *.hh *.hpp *.hxx *.c *.cc *.cpp *.cxx
+          EXCLUDE_PATTERNS       = */build/* */.git/*
+          EXTRACT_ALL            = YES
+          GENERATE_HTML          = NO
+          GENERATE_XML           = YES
+          WARN_IF_UNDOCUMENTED   = NO
+          QUIET                  = YES
+          EOF
+
+          doxygen build/Doxyfile
+          sphinx-build -b html docs build/site
+          deactivate
+
+      - name: Upload downloadable site artifact
+        uses: actions/upload-artifact@v7
+        with:
+          name: cpp-docs-site
+          path: build/site/
+          if-no-files-found: error
+          retention-days: 30
+
+      - name: Configure GitHub Pages
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: actions/configure-pages@v6
+
+      - name: Upload GitHub Pages artifact
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v5
+        with:
+          path: build/site/
+
+  deploy:
+    if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      pages: write
+      id-token: write
+
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v5
diff --git a/docs/conf.py b/docs/conf.py
new file mode 100644
index 0000000..3dfdb99
--- /dev/null
+++ b/docs/conf.py
@@ -0,0 +1,13 @@
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parents[1]
+
+project = "cpp-workspace"
+extensions = ["breathe"]
+
+breathe_projects = {
+    "cpp-workspace": str(ROOT / "build" / "doxygen" / "xml"),
+}
+breathe_default_project = "cpp-workspace"
+
+html_theme = "sphinx_rtd_theme"
diff --git a/docs/index.rst b/docs/index.rst
new file mode 100644
index 0000000..f73d0e0
--- /dev/null
+++ b/docs/index.rst
@@ -0,0 +1,8 @@
+cpp-workspace documentation
+===========================
+
+C++ API reference
+-----------------
+
+.. doxygenindex::
+   :project: cpp-workspace
diff --git a/docs/requirements.txt b/docs/requirements.txt
new file mode 100644
index 0000000..28179ea
--- /dev/null
+++ b/docs/requirements.txt
@@ -0,0 +1,3 @@
+breathe
+sphinx
+sphinx-rtd-theme