From 8c9ac8e8740f97a3c42a0039eb19f9de1f14d167 Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 30 Oct 2025 09:49:28 -0700 Subject: [PATCH 1/5] init doxygen deployement with CI --- .github/workflows/doxygen-pages.yml | 57 +++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) create mode 100644 .github/workflows/doxygen-pages.yml diff --git a/.github/workflows/doxygen-pages.yml b/.github/workflows/doxygen-pages.yml new file mode 100644 index 0000000..0aec9cb --- /dev/null +++ b/.github/workflows/doxygen-pages.yml @@ -0,0 +1,57 @@ +name: Build & Deploy Doxygen Docs + +# Run on pushes to the default branch and on PRs targeting it. +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +# Permissions needed for the deploy‑pages action. +permissions: + contents: read # checkout + pages: write # publish to GitHub Pages + id-token: write # OIDC token for the deploy action + +jobs: + build-docs: + runs-on: ubuntu-latest + steps: + + # ------------------------------------------------- + # 1️⃣ Checkout the repository + # ------------------------------------------------- + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 # required for proper git history when publishing + + # ------------------------------------------------- + # 2️⃣ Install Doxygen + Graphviz (for UML/diagrams) + # ------------------------------------------------- + - name: Install Doxygen and Graphviz + run: | + sudo apt-get update + sudo apt-get install -y doxygen graphviz + + # ------------------------------------------------- + # 3️⃣ Generate the documentation + # ------------------------------------------------- + - name: Build Doxygen docs + run: | + make docs + + # ------------------------------------------------- + # 4️⃣ Upload the generated HTML as an artifact + # ------------------------------------------------- + - name: Upload documentation artifact + uses: actions/upload-pages-artifact@v3 + with: + path: ./docs/html + + # ------------------------------------------------- + # 5️⃣ Deploy to GitHub Pages + # ------------------------------------------------- + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 From 9433574a2eaf6daa94d623b4283fd78638022cd6 Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 30 Oct 2025 09:54:00 -0700 Subject: [PATCH 2/5] change path for docxygen build --- .github/workflows/doxygen-pages.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/doxygen-pages.yml b/.github/workflows/doxygen-pages.yml index 0aec9cb..cd19077 100644 --- a/.github/workflows/doxygen-pages.yml +++ b/.github/workflows/doxygen-pages.yml @@ -47,7 +47,7 @@ jobs: - name: Upload documentation artifact uses: actions/upload-pages-artifact@v3 with: - path: ./docs/html + path: ./html # ------------------------------------------------- # 5️⃣ Deploy to GitHub Pages From 2e93bc5513be915356f60802c9ab1e88c483a3ef Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 30 Oct 2025 09:59:11 -0700 Subject: [PATCH 3/5] trying a new deployement --- .github/workflows/doxygen-pages.yml | 49 ++++++++++++++++++++--------- 1 file changed, 35 insertions(+), 14 deletions(-) diff --git a/.github/workflows/doxygen-pages.yml b/.github/workflows/doxygen-pages.yml index cd19077..d66602e 100644 --- a/.github/workflows/doxygen-pages.yml +++ b/.github/workflows/doxygen-pages.yml @@ -1,20 +1,20 @@ name: Build & Deploy Doxygen Docs -# Run on pushes to the default branch and on PRs targeting it. +# Run on every push (or PR) to the default branch (usually `main`) on: push: branches: [ main ] pull_request: branches: [ main ] -# Permissions needed for the deploy‑pages action. +# Permissions required for the deploy‑pages action permissions: - contents: read # checkout - pages: write # publish to GitHub Pages - id-token: write # OIDC token for the deploy action + contents: read + pages: write + id-token: write jobs: - build-docs: + build-and-deploy: runs-on: ubuntu-latest steps: @@ -24,10 +24,10 @@ jobs: - name: Checkout repository uses: actions/checkout@v4 with: - fetch-depth: 0 # required for proper git history when publishing + fetch-depth: 0 # needed for proper git history when publishing # ------------------------------------------------- - # 2️⃣ Install Doxygen + Graphviz (for UML/diagrams) + # 2️⃣ Install Doxygen + Graphviz (for diagrams) # ------------------------------------------------- - name: Install Doxygen and Graphviz run: | @@ -35,23 +35,44 @@ jobs: sudo apt-get install -y doxygen graphviz # ------------------------------------------------- - # 3️⃣ Generate the documentation + # 3️⃣ Build the documentation # ------------------------------------------------- - name: Build Doxygen docs run: | - make docs + # Show the Doxyfile so you can confirm the output dirs + echo "===== Doxyfile =====" + cat Doxyfile + echo "====================" + # Run Doxygen – it will write to ./docs/html because of your config + doxygen Doxyfile # ------------------------------------------------- - # 4️⃣ Upload the generated HTML as an artifact + # 4️⃣ Debug: list the generated files (helps catch path issues) + # ------------------------------------------------- + - name: List generated files (debug) + run: | + echo "=== Repository tree after Doxygen ===" + ls -R . + echo "=== Looking for docs/html ===" + if [ -d "./docs/html" ]; then + echo "✅ Found ./docs/html" + else + echo "❌ ./docs/html NOT found" + fi + + # ------------------------------------------------- + # 5️⃣ Upload the HTML artifact (point to docs/html) # ------------------------------------------------- - name: Upload documentation artifact uses: actions/upload-pages-artifact@v3 with: - path: ./html + path: ./docs/html # <‑‑ UPDATED PATH + name: github-pages + retention-days: 1 # keep for a day (adjust as you wish) # ------------------------------------------------- - # 5️⃣ Deploy to GitHub Pages + # 6️⃣ Deploy to GitHub Pages # ------------------------------------------------- - name: Deploy to GitHub Pages id: deployment - uses: actions/deploy-pages@v4 + uses: actions/deploy-pages@v4 \ No newline at end of file From 1462d47a40e82fd458e24ea6e6f238b7c66d2171 Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 30 Oct 2025 10:04:12 -0700 Subject: [PATCH 4/5] adding path --- .github/workflows/doxygen-pages.yml | 36 ++++++++++++++++++----------- 1 file changed, 23 insertions(+), 13 deletions(-) diff --git a/.github/workflows/doxygen-pages.yml b/.github/workflows/doxygen-pages.yml index d66602e..3dc2f2b 100644 --- a/.github/workflows/doxygen-pages.yml +++ b/.github/workflows/doxygen-pages.yml @@ -1,23 +1,34 @@ name: Build & Deploy Doxygen Docs -# Run on every push (or PR) to the default branch (usually `main`) +# ------------------------------------------------- +# Trigger on pushes (or PRs) to the default branch +# ------------------------------------------------- on: push: branches: [ main ] pull_request: branches: [ main ] -# Permissions required for the deploy‑pages action +# ------------------------------------------------- +# Permissions needed for the deploy‑pages action +# ------------------------------------------------- permissions: - contents: read - pages: write - id-token: write + contents: read # checkout + pages: write # create a Pages deployment + id-token: write # OIDC token for auth jobs: build-and-deploy: runs-on: ubuntu-latest - steps: + # ------------------------------------------------- + # IMPORTANT: Declare the Pages environment here + # ------------------------------------------------- + environment: + name: github-pages # <-- matches the environment GitHub creates for Pages + url: ${{ steps.deploy.outputs.page_url }} # optional, lets you reference the URL later + + steps: # ------------------------------------------------- # 1️⃣ Checkout the repository # ------------------------------------------------- @@ -39,25 +50,24 @@ jobs: # ------------------------------------------------- - name: Build Doxygen docs run: | - # Show the Doxyfile so you can confirm the output dirs echo "===== Doxyfile =====" cat Doxyfile echo "====================" - # Run Doxygen – it will write to ./docs/html because of your config doxygen Doxyfile # ------------------------------------------------- - # 4️⃣ Debug: list the generated files (helps catch path issues) + # 4️⃣ Debug: list generated files (helps catch path issues) # ------------------------------------------------- - name: List generated files (debug) run: | echo "=== Repository tree after Doxygen ===" ls -R . - echo "=== Looking for docs/html ===" + echo "Looking for ./docs/html ..." if [ -d "./docs/html" ]; then echo "✅ Found ./docs/html" else echo "❌ ./docs/html NOT found" + exit 1 fi # ------------------------------------------------- @@ -66,13 +76,13 @@ jobs: - name: Upload documentation artifact uses: actions/upload-pages-artifact@v3 with: - path: ./docs/html # <‑‑ UPDATED PATH + path: ./docs/html # <-- your actual output folder name: github-pages - retention-days: 1 # keep for a day (adjust as you wish) + retention-days: 1 # ------------------------------------------------- # 6️⃣ Deploy to GitHub Pages # ------------------------------------------------- - name: Deploy to GitHub Pages - id: deployment + id: deploy # gives us the output `page_url` if we need it uses: actions/deploy-pages@v4 \ No newline at end of file From a22a5f42b44e68edecc51dde9cdb75ffa4149cd4 Mon Sep 17 00:00:00 2001 From: Chris Date: Thu, 30 Oct 2025 10:35:32 -0700 Subject: [PATCH 5/5] update per github template --- .github/workflows/doxygen-pages.yml | 103 ++++++++-------------------- 1 file changed, 29 insertions(+), 74 deletions(-) diff --git a/.github/workflows/doxygen-pages.yml b/.github/workflows/doxygen-pages.yml index 3dc2f2b..14505bc 100644 --- a/.github/workflows/doxygen-pages.yml +++ b/.github/workflows/doxygen-pages.yml @@ -1,88 +1,43 @@ -name: Build & Deploy Doxygen Docs +# Simple workflow for deploying static content to GitHub Pages +name: Deploy static content to Pages -# ------------------------------------------------- -# Trigger on pushes (or PRs) to the default branch -# ------------------------------------------------- on: + # Runs on pushes targeting the default branch push: - branches: [ main ] - pull_request: - branches: [ main ] + branches: ["main"] -# ------------------------------------------------- -# Permissions needed for the deploy‑pages action -# ------------------------------------------------- + # Allows you to run this workflow manually from the Actions tab + workflow_dispatch: + +# Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages permissions: - contents: read # checkout - pages: write # create a Pages deployment - id-token: write # OIDC token for auth + contents: read + pages: write + id-token: write -jobs: - build-and-deploy: - runs-on: ubuntu-latest +# Allow only one concurrent deployment, skipping runs queued between the run in-progress and latest queued. +# However, do NOT cancel in-progress runs as we want to allow these production deployments to complete. +concurrency: + group: "pages" + cancel-in-progress: false - # ------------------------------------------------- - # IMPORTANT: Declare the Pages environment here - # ------------------------------------------------- +jobs: + # Single deploy job since we're just deploying + deploy: environment: - name: github-pages # <-- matches the environment GitHub creates for Pages - url: ${{ steps.deploy.outputs.page_url }} # optional, lets you reference the URL later - + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + runs-on: ubuntu-latest steps: - # ------------------------------------------------- - # 1️⃣ Checkout the repository - # ------------------------------------------------- - - name: Checkout repository + - name: Checkout uses: actions/checkout@v4 - with: - fetch-depth: 0 # needed for proper git history when publishing - - # ------------------------------------------------- - # 2️⃣ Install Doxygen + Graphviz (for diagrams) - # ------------------------------------------------- - - name: Install Doxygen and Graphviz - run: | - sudo apt-get update - sudo apt-get install -y doxygen graphviz - - # ------------------------------------------------- - # 3️⃣ Build the documentation - # ------------------------------------------------- - - name: Build Doxygen docs - run: | - echo "===== Doxyfile =====" - cat Doxyfile - echo "====================" - doxygen Doxyfile - - # ------------------------------------------------- - # 4️⃣ Debug: list generated files (helps catch path issues) - # ------------------------------------------------- - - name: List generated files (debug) - run: | - echo "=== Repository tree after Doxygen ===" - ls -R . - echo "Looking for ./docs/html ..." - if [ -d "./docs/html" ]; then - echo "✅ Found ./docs/html" - else - echo "❌ ./docs/html NOT found" - exit 1 - fi - - # ------------------------------------------------- - # 5️⃣ Upload the HTML artifact (point to docs/html) - # ------------------------------------------------- - - name: Upload documentation artifact + - name: Setup Pages + uses: actions/configure-pages@v5 + - name: Upload artifact uses: actions/upload-pages-artifact@v3 with: - path: ./docs/html # <-- your actual output folder - name: github-pages - retention-days: 1 - - # ------------------------------------------------- - # 6️⃣ Deploy to GitHub Pages - # ------------------------------------------------- + # Upload entire repository + path: './docs/html' - name: Deploy to GitHub Pages - id: deploy # gives us the output `page_url` if we need it + id: deployment uses: actions/deploy-pages@v4 \ No newline at end of file