Develop

.github/workflows/doxygen-pages.yml

@@ -0,0 +1,86 @@
+name: Build and Deploy Docs
+
+on:
+  push:
+    branches:
+      - main
+    paths:
+      - Doxygen
+      - README.md
+      - docs/**
+      - '**/*.md'
+      - '**/*.dox'
+      - '**/*.h'
+      - '**/*.hh'
+      - '**/*.hpp'
+      - '**/*.hxx'
+      - '**/*.c'
+      - '**/*.cc'
+      - '**/*.cpp'
+      - '**/*.cxx'
+      - '**/*.py'
+      - .github/workflows/doxygen-pages.yml
+  pull_request:
+    branches:
+      - main
+    paths:
+      - Doxygen
+      - README.md
+      - docs/**
+      - '**/*.md'
+      - '**/*.dox'
+      - '**/*.h'
+      - '**/*.hh'
+      - '**/*.hpp'
+      - '**/*.hxx'
+      - '**/*.c'
+      - '**/*.cc'
+      - '**/*.cpp'
+      - '**/*.cxx'
+      - '**/*.py'
+      - .github/workflows/doxygen-pages.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: true
+
+jobs:
+  build-docs:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Install Doxygen
+        run: sudo apt-get update && sudo apt-get install -y doxygen
+
+      - name: Build HTML documentation
+        run: |
+          doxygen Doxygen
+          touch docs/html/.nojekyll
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: docs/html
+
+  deploy-pages:
+    if: github.event_name != 'pull_request' && github.ref_name == github.event.repository.default_branch
+    needs: build-docs
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

Doxygen

@@ -0,0 +1,22 @@
+PROJECT_NAME = "Fabric"
+OUTPUT_DIRECTORY = docs
+FULL_PATH_NAMES = YES
+STRIP_FROM_PATH = .
+MARKDOWN_SUPPORT = YES
+AUTOLINK_SUPPORT = YES
+USE_MDFILE_AS_MAINPAGE = README.md
+INPUT = .
+FILE_PATTERNS = *.c *.cc *.cpp *.cxx *.h *.hh *.hpp *.hxx *.md *.markdown *.dox *.py
+RECURSIVE = YES
+EXCLUDE = ./build ./install ./log ./docs/html
+EXTRACT_ALL = YES
+EXTRACT_PRIVATE = YES
+EXTRACT_STATIC = YES
+WARN_IF_UNDOCUMENTED = YES
+SOURCE_BROWSER = NO
+IMAGE_PATH = docs/images
+GENERATE_HTML = YES
+HTML_OUTPUT = html
+GENERATE_TREEVIEW = NO
+SEARCHENGINE = YES
+GENERATE_LATEX = NO

docs/readme.md

@@ -0,0 +1,15 @@
+# Docs
+
+The documentation site is generated with Doxygen from the existing Markdown in this `docs/` tree together with comments from the source code. The Doxygen configuration lives at the repository root in [`Doxygen`](../Doxygen).
+
+```bash
+# install doxygen if it is not already available
+sudo apt-get update && sudo apt-get install -y doxygen
+
+# from the repository root
+doxygen Doxygen
+```
+
+The generated HTML site is written to `docs/html/` and the entry page is `docs/html/index.html`.
+
+For GitHub Pages, this repository can use GitHub Actions as both the build source and the deployment source. The workflow in `.github/workflows/doxygen-pages.yml` rebuilds the site whenever documentation or source files change and deploys the generated `docs/html/` artifact to Pages.