Skip to content

Publish stable API documentation with Sourcey and GitHub Pages - #403

Open
RYDE-PLAY wants to merge 1 commit into
laurencelundblade:masterfrom
RYDE-PLAY:docs/sourcey-pages
Open

Publish stable API documentation with Sourcey and GitHub Pages#403
RYDE-PLAY wants to merge 1 commit into
laurencelundblade:masterfrom
RYDE-PLAY:docs/sourcey-pages

Conversation

@RYDE-PLAY

Copy link
Copy Markdown

Hi, I put together a complete implementation for #395.

This publishes documentation for the current stable master branch while keeping the existing QCBOR v2 alpha documentation clearly linked and separate.

What this adds:

  • a Sourcey site combining the project guide, focused guides, and Doxygen API reference
  • Doxygen XML output and public API groups for common types, decoding, encoding, spiffy decode, and buffer utilities
  • full-text search across 1,296 guide and API entries
  • API source links pinned to the exact build commit
  • a GitHub Pages workflow that builds on documentation PRs and deploys after pushes to master
  • a stable-documentation link in the README, with the existing Security Theory site labeled as the v2 alpha documentation
  • a small API-only style adjustment that removes Sourcey's duplicated Doxygen title and summary

The group additions are documentation comments around the existing public headers; they do not change compiled behavior. Private implementation symbols and qcbor_private.h are excluded from the generated API.

Validation performed:

  • pnpm install --frozen-lockfile
  • pnpm run docs
  • generated-site check: 22 HTML pages, 0 broken internal links, 0 private API pages, and 60 revision-pinned source links
  • desktop and mobile navigation, search, and representative function-page checks
  • make warn
  • ./qcbortest — 76 tests passed, 0 failed
  • git diff --check

The Doxygen step still prints the existing undocumented-symbol and obsolete-option warnings from the source and Doxyfile, but completes successfully.

One repository setting is needed after merge: under Settings → Pages → Build and deployment, select GitHub Actions as the source. After that, the included workflow will publish and update the site automatically.

I would be happy to adjust the organization, wording, colors, or workflow split to better match the project's preferences.

Closes #395.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Online API documentation

1 participant