Enhance FIREQ documentation structure and build process - #1
Merged
Conversation
f-riente
added
documentation
fabiocalabrese
approved these changes
Aug 5, 2026
Contributor
There was a problem hiding this comment.
Pull request overview
This PR restructures the FIREQ documentation to stage component docs under docs/repos/, expands the Sphinx build configuration for richer MyST/Sphinx features, and updates the GitHub Actions pipeline to build (and conditionally deploy) the documentation to GitHub Pages.
Changes:
- Replace the old
docs/imported/*doc sync approach with anrsync-based staging layout underdocs/repos/*. - Add/adjust Sphinx configuration and theming (extensions, autosummary template, custom CSS, logo) and introduce new landing/getting-started pages.
- Update the GitHub Actions workflow to build integrated docs, upload a preview artifact, and deploy to Pages on main pushes.
Reviewed changes
Copilot reviewed 12 out of 17 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/sync_component_docs.sh | Switches to rsync-based staging of component docs under docs/repos/. |
| requirements.txt | Adds sphinx-design to support card/grid directives in MyST. |
| fireq-release.yaml | Updates component refs used by the integrated docs build workflow. |
| docs/project_info.md | Adds a project resources/contact page. |
| docs/index.md | Replaces the landing page with a new structure and component/doc cards + updated toctree. |
| docs/getting_started.md | Adds a quick-start / getting-started guide for hardware setup and first run. |
| docs/conf.py | Expands Sphinx configuration for autodoc/autosummary + theming + exclude patterns. |
| docs/components/server.md | Removes legacy component wrapper page (imported-docs based). |
| docs/components/firmware.md | Removes legacy component wrapper page (imported-docs based). |
| docs/components/client.md | Removes legacy component wrapper page (imported-docs based). |
| docs/_templates/autosummary/class.rst | Adds a custom autosummary class template. |
| docs/_static/fireq.css | Adds custom styling for the docs theme and cards. |
| docs/_static/fireq-logo.svg | Adds a FIREQ logo for the docs theme. |
| .gitignore | Ignores the generated docs/repos/ staging directory. |
| .github/workflows/deploy-docs.yml | Builds integrated docs in CI, uploads preview artifact, and deploys to Pages on main pushes. |
Suppressed comments (1)
docs/getting_started.md:54
- This step includes an unresolved placeholder version ("PYNQ v???"), which will appear in the published docs and makes the instructions non-actionable.
1. **Download the Linux Image**:
* **For RFSoC4x2**: Download the official PYNQ v??? image from [PYNQ Boards](http://www.pynq.io/boards.html).
* **For ZCU216**: Use our custom pre-configured FIREQ ZCU216 [image](https://drive.google.com/file/d/1SGH7_pw0L9ww165A97FIzp7Xo3PNwCV2/view?usp=sharing)
💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.
Comment on lines
114
to
+115
| - name: Configure GitHub Pages | ||
| if: github.event_name == 'push' && github.ref == 'refs/heads/main' |
Contributor
Author
There was a problem hiding this comment.
This is what we want:
push/merge on main → build + artifact + public deploy
push on docs/** → build + artifact, no deploy
repository_dispatch → build + artifact, no deploy
workflow_dispatch → build + artifact, no deploy
Comment on lines
+5
to
+8
| For a complete architectural overview and capabilities of FIREQ, please cite or read our instrumentation paper: | ||
|
|
||
| > **[Insert Paper Title Here]** *(Authors et al., 2026)* | ||
| > [Link to Paper/DOI](#) |
Contributor
Author
|
I think we are ready to merge once the other repos are merged into main. |
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 13 out of 21 changed files in this pull request and generated 3 comments.
Suppressed comments (1)
docs/project_info.md:12
- This section still contains publication placeholders ("Insert Paper Title Here" and a dummy DOI link), which will ship into the rendered docs.
For a complete architectural overview and capabilities of FIREQ, please read our paper:
> **[Insert Paper Title Here]** *(Authors et al., 2026)*
> [Link to Paper/DOI](#)
Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>
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
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.
Setup the triggering system and deploy of the FIREQ documentation on pages.