Publish stable API documentation with Sourcey and GitHub Pages

.github/workflows/docs.yml

@@ -0,0 +1,70 @@
+name: Documentation
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+    paths:
+      - ".github/workflows/docs.yml"
+      - "docs/**"
+      - "doc/**"
+      - "doxygen/**"
+      - "inc/**"
+      - "README.md"
+      - "package.json"
+      - "pnpm-lock.yaml"
+      - "sourcey.config.ts"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    name: Build documentation
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install Doxygen
+        run: sudo apt-get update && sudo apt-get install --yes doxygen
+
+      - uses: pnpm/action-setup@v4
+        with:
+          version: 11.8.0
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - name: Install documentation dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build documentation
+        run: pnpm run docs
+
+      - name: Upload Pages artifact
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    name: Deploy documentation
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      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@v4

.gitignore

@@ -55,3 +55,8 @@ dkms.conf
 qcbortest
 qcbormin
 
+# Generated documentation
+node_modules/
+site/
+doxygen/html/
+doxygen/xml/

README.md

@@ -79,7 +79,11 @@ It includes:
 
 ## Documentation
 
-Full API documentation is at https://www.securitytheory.com/qcbor-docs/
+Documentation for the current stable branch, including the full API
+reference, is published at https://laurencelundblade.github.io/QCBOR/.
+
+Documentation for the QCBOR v2 alpha branch is at
+https://www.securitytheory.com/qcbor-docs/.
 
 
 ## Spiffy Decode

docs/sourcey.css

@@ -0,0 +1,17 @@
+/* Doxygen pages include their title in the generated body. Sourcey already
+ * renders the same title in the page header, so keep one visible heading. */
+body:has([data-sourcey-sidebar-tab="api"])
+  #content-area
+  > header
+  + .prose
+  > h1:first-of-type {
+  display: none;
+}
+
+body:has([data-sourcey-sidebar-tab="api"])
+  #content-area
+  > header:has(.page-description span)
+  + .prose
+  > p:nth-of-type(2) {
+  display: none;
+}

doxygen/Doxyfile

@@ -928,7 +928,7 @@ EXCLUDE_SYMLINKS       = NO
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories for example use the pattern */test/*
 
-EXCLUDE_PATTERNS       =
+EXCLUDE_PATTERNS       = */qcbor_private.h
 
 # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
 # (namespaces, classes, functions, etc.) that should be excluded from the
@@ -939,7 +939,10 @@ EXCLUDE_PATTERNS       =
 # Note that the wildcards are matched against the file with absolute path, so to
 # exclude all test directories use the pattern */test/*
 
-EXCLUDE_SYMBOLS        =
+EXCLUDE_SYMBOLS        = QCBOREncode_Private_* \
+                         QCBORDecode_Private_* \
+                         QCBOR_Private_* \
+                         __*
 
 # The EXAMPLE_PATH tag can be used to specify one or more files or directories
 # that contain example code fragments that are included (see the \include
@@ -2045,7 +2048,7 @@ MAN_LINKS              = NO
 # captures the structure of the code including all documentation.
 # The default value is: NO.
 
-GENERATE_XML           = NO
+GENERATE_XML           = YES
 
 # The XML_OUTPUT tag is used to specify where the XML pages will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

inc/qcbor/UsefulBuf.h

@@ -177,6 +177,13 @@ extern "C" {
 #endif
 #endif
 
+/**
+ * @defgroup UsefulBuf Buffer Utilities
+ * @ingroup QCBORAPI
+ * @brief Bounds-checked input and output buffer types used by QCBOR.
+ * @{
+ */
+
 /**
  * @file UsefulBuf.h
  *
@@ -2550,11 +2557,12 @@ static inline UsefulBufC UsefulInputBuf_RetrieveUndecodedInput(UsefulInputBuf *p
    return pMe->UB;
 }
 
+/** @} */
+
 
 #ifdef __cplusplus
 }
 #endif
 
 #endif  /* _UsefulBuf_h */
 
-

inc/qcbor/qcbor.h

@@ -37,5 +37,10 @@
  * into four include files).
  */
 
+/**
+ * @defgroup QCBORAPI QCBOR API Reference
+ * @brief Public interfaces for encoding, decoding and safely handling CBOR data.
+ */
+
 #include "qcbor_encode.h"
 #include "qcbor_decode.h"

inc/qcbor/qcbor_common.h

@@ -40,6 +40,13 @@ extern "C" {
 #endif
 #endif
 
+/**
+ * @defgroup QCBORCommon Common
+ * @ingroup QCBORAPI
+ * @brief Shared types, error codes, tags and limits used by QCBOR.
+ * @{
+ */
+
 
 /**
  * @file qcbor_common.h
@@ -595,6 +602,7 @@ qcbor_err_to_str(QCBORError uErr);
  */
 #define QCBOR_MAX_ITEMS_IN_MAP  (QCBOR_MAX_ITEMS_IN_ARRAY/2)
 
+/** @} */
 
 #ifdef __cplusplus
 }

inc/qcbor/qcbor_decode.h

@@ -48,6 +48,13 @@ extern "C" {
 #endif
 #endif
 
+/**
+ * @defgroup QCBORDecode Decoding
+ * @ingroup QCBORAPI
+ * @brief Streaming and traversal APIs for decoding CBOR data.
+ * @{
+ */
+
 
 /**
  * @file qcbor_decode.h
@@ -1705,6 +1712,8 @@ QCBORDecode_SetError(QCBORDecodeContext *pMe, QCBORError uError)
 #error QCBOR_NON_BOUNDED_OFFSET is too large
 #endif
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

inc/qcbor/qcbor_encode.h

@@ -48,6 +48,13 @@ extern "C" {
 #endif
 #endif
 
+/**
+ * @defgroup QCBOREncode Encoding
+ * @ingroup QCBORAPI
+ * @brief APIs for encoding CBOR values, arrays, maps, tags and strings.
+ * @{
+ */
+
 
 /**
  * @file qcbor_encode.h
@@ -4386,6 +4393,8 @@ QCBOREncode_Tell(QCBOREncodeContext *pMe)
  *    END OF PRIVATE INLINE IMPLEMENTATION                                  *
  * ======================================================================== */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

inc/qcbor/qcbor_spiffy_decode.h

@@ -24,6 +24,13 @@ extern "C" {
 #endif
 #endif
 
+/**
+ * @defgroup QCBORSpiffyDecode Spiffy Decode
+ * @ingroup QCBORAPI
+ * @brief Higher-level typed and map-oriented decoding helpers.
+ * @{
+ */
+
 
 /**
  * @file qcbor_spiffy_decode.h
@@ -3065,6 +3072,8 @@ QCBORDecode_GetBinaryUUIDInMapSZ(QCBORDecodeContext *pMe,
  *    END OF PRIVATE INLINE IMPLEMENTATION                                  *
  * ======================================================================== */
 
+/** @} */
+
 #ifdef __cplusplus
 }
 #endif

index.md

@@ -0,0 +1,30 @@
+---
+title: QCBOR Documentation
+description: Stable-branch guides and API reference for the QCBOR CBOR encoder and decoder.
+---
+
+# QCBOR Documentation
+
+QCBOR is a commercial-quality C encoder and decoder for CBOR. It is designed
+for portability, predictable memory use and secure handling of binary data.
+
+This site is generated from the current `master` branch. It keeps the project
+guide, focused topic guides and the API reference together and links every API
+entry back to its source revision.
+
+## Start here
+
+- [Project guide](/QCBOR/guides/readme.html) — features, examples, building,
+  configuration and code-size guidance.
+- [API reference](/QCBOR/api/QCBORAPI.html) — encoding, decoding, common types and
+  bounds-checked buffer utilities.
+- [Types and tagging](/QCBOR/guides/doc/tagging.html) — how CBOR tags and borrowed
+  tag content are represented by QCBOR.
+- [Tag 1 FAQ](/QCBOR/guides/doc/timetag1faq.html) — implementation guidance for
+  epoch-based time values.
+
+## Version note
+
+These pages document the stable `master` branch. The separately maintained
+[QCBOR v2 alpha documentation](https://www.securitytheory.com/qcbor-docs/)
+covers the in-development `dev` branch.

package.json

@@ -0,0 +1,13 @@
+{
+  "name": "qcbor-documentation",
+  "private": true,
+  "scripts": {
+    "docs:doxygen": "cd doxygen && doxygen Doxyfile",
+    "docs:build": "sourcey build -o site",
+    "docs": "pnpm docs:doxygen && pnpm docs:build"
+  },
+  "devDependencies": {
+    "sourcey": "3.6.5"
+  },
+  "packageManager": "pnpm@11.8.0"
+}