Add full Sphinx documentation site#256
Merged
ruck314 merged 15 commits intopre-releasefrom Mar 29, 2026
Merged
Conversation
- Pin sphinx==7.4.7, sphinx-rtd-theme==2.0.0, breathe==4.35.0, sphinx-copybutton==0.5.2 - Add docs/Makefile with html, clean, and help targets (tab-indented recipes) - Append docs/_build/ and docs/_doxygen/ to .gitignore
- OPTIMIZE_OUTPUT_FOR_C=YES for clean C struct/function rendering - GENERATE_XML=YES, GENERATE_HTML=NO (XML consumed by Breathe only) - EXTRACT_STATIC=YES to capture static inline userspace API functions - DMA_IN_KERNEL intentionally absent from PREDEFINED so #ifndef DMA_IN_KERNEL blocks (the public userspace API) are visible to Doxygen - INPUT=../include/ relative to docs/ directory - OUTPUT_DIRECTORY=_doxygen (relative to docs/, produces docs/_doxygen/)
- Add docs/conf.py with Breathe, sphinx_rtd_theme, sphinx-copybutton config - breathe_projects path: _doxygen/xml (relative to docs/) - breathe_domain_by_extension forces C domain for .h/.c files - DOCS_VERSION env var for CI version injection; falls back to "dev" - Add docs/index.rst with toctree for all four Diataxis sections - Add stub index files for tutorials/, how-to/, reference/, explanation/ - Move docs/DMA.rst -> docs/reference/dma-legacy.rst and add to reference toctree to avoid Sphinx orphan warning
- Remove display_version from html_theme_options (unsupported in sphinx_rtd_theme 3.x) - Remove html_static_path entry for non-existent _static dir (create empty dir instead)
Add /** @brief */ Doxygen comments to all 24 undocumented ioctl command code macros in the Commands block (0x1001-0x1019, with intentional gap at 0x100E). Comments follow the same style used in AxisDriver.h. Doxygen XML now contains 31 define entries for DmaDriver_8h.xml, confirming all macros are parsed and documented.
…d requirements Create docs/reference/dma-api.rst and docs/reference/axis-api.rst using the doxygenfile:: Breathe directive for DmaDriver.h and AxisDriver.h respectively. Update docs/reference/index.rst toctree to include dma-api, axis-api, and the Wave 2 placeholder entries (ioctl-table, module-parameters, device-nodes, dma-legacy). Update docs/requirements.txt to pin verified working versions: sphinx==8.1.3, sphinx-rtd-theme==3.0.2, breathe==4.36.0, sphinx-copybutton==0.5.2. Sphinx build succeeds with 4 expected warnings (3 for not-yet-created Wave 2 RST files, resolved in plan 02-02).
- 24 DmaDriver.h codes (0x1001–0x1019, gap at 0x100E) - 2 AxisDriver.h codes (0x2001, 0x2002) - 1 AxiVersion.h code (0x1200) - 6 GpuAsync.h codes (0x8002–0x8007) - Uses list-table directives grouped by header file - Includes :c:func: cross-references to wrapper functions
- module-parameters.rst: all 19 datadev parameters with defaults and descriptions (cfgTxCount, cfgRxCount, cfgSize, cfgMode, cfgCont, cfgIrqHold, cfgIrqDis, cfgBgThold0-7, cfgDevName, cfgTimeout, cfgDebug) - device-nodes.rst: /dev/datadev_N naming (sequential and PCI bus-based), permissions (0666), /proc diagnostic interface, multi-device behavior - index.rst toctree already complete from Wave 1 (no changes needed) - Sphinx build: succeeded with 1 pre-existing warning (dma-api.rst), no orphan warnings for any new reference pages
- Write docs/tutorials/first-transfer.rst: 8-section PCIe x86 loopback tutorial covering hardware detection, build, insmod, /proc inspection, dmaLoopTest, and cleanup; includes loopback firmware prerequisite warning - Write docs/tutorials/gpudirect-first.rst: 8-section GPUDirect tutorial covering display manager disable, NVIDIA open kernel module install, GRUB IOMMU config, comp_and_load_drivers.sh, GPUDirect support check, and rdmaTest; prominent warning for open vs closed driver distinction - Update docs/tutorials/index.rst toctree to include both new pages; remove placeholder note block
- build-and-load.rst: build, insmod with parameters, modprobe.d persistent config - cross-compile-rce.rst: SLAC shortcut (make rce) and non-SLAC ARM/x86 buildroot paths - yocto-integration.rst: BitBake recipe copy, layer.conf, DMA buffer vars, device tree node - dkms-install.rst: DKMS lifecycle with warning about commented-out PACKAGE_VERSION - gpudirect-setup.rst: NVIDIA open kernel modules setup with open-vs-closed driver warning - multi-channel.rst: dmaSetMaskBytes API with dmaRetIndex pairing warning - index.rst: toctree updated with all 6 entries, placeholder note removed
…-04) - architecture.rst: hardware_functions vtable, component relationships, BAR0 memory map, and PCI device identification - dma-modes.rst: BUFF_COHERENT/BUFF_STREAM/BUFF_ARM_ACP modes, cfgMode=4 rejection by data_dev, buffer pool pre-allocation, state machine, zero-copy - axi-stream-protocol.rst: TLAST framing, fuser/luser/cont bit layout, TDEST channel routing, AxisG2 engine overview - kernel-compatibility.rst: all nine LINUX_VERSION_CODE guards, RHEL backport detection, min kernel 3.10 and max tested 6.8+ - explanation/index.rst: toctree updated with all four pages; placeholder removed
ruck314
changed the title
JJL772
approved these changes
Mar 29, 2026
Member
JJL772
left a comment
JJL772
left a comment
There was a problem hiding this comment.
I think everything here is generally correct.
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
2 participants
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.
Summary
docs/What's included
Infrastructure (Phase 1)
docs/conf.py,docs/Doxyfile,docs/Makefile,docs/requirements.txtdocs/_build/,docs/_doxygen/) excluded from gitReference (Phase 2)
docs/reference/dma-api.rst— full DmaDriver.h API via Breathedocs/reference/axis-api.rst— full AxisDriver.h API via Breathedocs/reference/ioctl-table.rst— all 33 ioctl codes across 4 headersdocs/reference/module-parameters.rst— all 19 datadev module parameters with defaultsdocs/reference/device-nodes.rst— /dev/datadev_N naming, permissions, /proc interface/** @brief */Doxygen comments to 24 previously undocumented ioctl macros ininclude/DmaDriver.hTutorials (Phase 3)
docs/tutorials/first-transfer.rst— PCIe x86 end-to-end loopback tutorialdocs/tutorials/gpudirect-first.rst— GPUDirect RDMA first-use tutorialHow-to Guides (Phase 3)
Explanation (Phase 3)
Publishing (Phase 4)
.github/workflows/docs.yml— builds and deploys to GitHub Pages on every tag push viapeaceiris/actions-gh-pages@v3README.md— docs link added at topdocs/how-to/github-pages-setup.rst— one-time GitHub Pages activation instructionsPost-merge setup
After merging and pushing a tag, activate GitHub Pages:
Settings → Pages → Source: Deploy from a branch → Branch:
gh-pages/(root)→ SaveSite will be live at: https://slaclab.github.io/aes-stream-drivers