Repository navigation
Add Doxygen/Sphinx documentation with test-sourced how-to guides, and publish to GitHub Pages - #5
Merged
Merged
Conversation
bfierz
commented
Sep 19, 2026
bfierz
commented
Contributor
- Sets up a Doxygen → Breathe → Sphinx documentation pipeline behind a new WEAVER_BUILD_DOCS CMake option.
- Adds 13 how-to guides under doc/sphinx/howto.rst, each backed by a real, compiled, executed Catch2 test in doc/snippets/ (tagged [doc]).
- Scalar ops: add, select (branchless max), sqrt, rcp/rsqrt, sgn, tolerance-based equal, any-reduction, dot.
- Eigen integration: vector arithmetic, squaredNorm, cross, branchless select over an Eigen::Matrix, AlignedBox::merged
- doc/tools/extract_asm.py disassembles each example's dedicated *_asm.cpp function (compiled in isolation in the new weaver_doc_asm OBJECT library) via objdump, strips the CET landing pad and inter-function alignment padding, and prepends a comment documenting which register holds which parameter.
- Adds .github/workflows/docs.yml: builds the docs on every push/PR to main, and deploys the result to GitHub Pages on pushes to main (gated so PRs only validate, never publish).
…ippets Doc examples live as tagged Catch2 tests under doc/snippets/, compiled and run as part of weaver_tests, so a how-to guide can't silently drift out of sync with the API it demonstrates -- a broken literalinclude reference fails the Sphinx build (run with -W). Wired up as an opt-in WEAVER_BUILD_DOCS CMake target and a separate CI workflow.
doc/snippets/float8_asm.cpp adds a small function whose only job is to be compiled in isolation and disassembled, so the how-to guide can show the actual vector instruction the compiler emits instead of just asserting FloatWeaver is vectorized. Its operands are taken as parameters rather than literals; literal operands let the compiler constant-fold the addition away, leaving no vector instruction to show. doc/tools/extract_asm.py pulls one function's disassembly out of the object file (objdump -d -C), and a new weaver-asm Sphinx directive (conf.py) embeds it, mirroring how WEAVER_DOXYGEN_XML_DIR already feeds Breathe.
…p the extracted listings Adds sqrt/rcp/rsqrt/sgn/tolerance-compare/any/dot guides plus a new Eigen-integration section (vector arithmetic, squaredNorm, cross, branchless select, AlignedBox merge), each with real compiled-and- disassembled asm like the existing add/select guides. Also trims the CET landing pad and inter-function alignment padding that were cluttering every listing, and annotates each one with which register holds which parameter (hand-verified against the real System V AMD64 disassembly, the only calling convention WEAVER_BUILD_DOCS targets).
Adds a deploy job (gated to main pushes, so PRs still only build and validate) that uploads the Sphinx output as a Pages artifact and publishes it via actions/deploy-pages.
…n convention The arm-linux-gnueabihf/QEMU CI leg failed: NEON has no native sqrt instruction, so weaver::sqrt there is built from an approximate rsqrt (see intrinsics_neon.cpp), not bit-exact like the x86 vsqrtps path. The guide's REQUIRE used exact `==`, which happened to round-trip on every other backend but missed by an ULP here. Switched to weaver::equal(..., tol) with 1e-5f, the same tolerance the library's own "Sqrt FloatN" test (src/tests/simd.cpp) already uses for the same reason.
bfierz
force-pushed
the
feature/documentation-setup
branch
from
September 20, 2026 19:17
33df614 to
ab648f2
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.