full docs, pages, graphviz, readme and citation overhaul#9
Merged
Conversation
There was a problem hiding this comment.
Pull request overview
This PR performs a broad documentation + project-metadata refresh, adds an interactive Graphviz-generated workflow/logic map under docs/flowchart/, and updates CI to run the fast test suite against both a pinned dependency floor and an unpinned “latest” canary.
Changes:
- Expand and reorganize
README.mdwith updated API examples, archive/schema documentation, and links to the new flowchart pages. - Add flowchart generation assets (
docs/flowchart/*) including abuild.pyrenderer and vendored pan/zoom JS for an interactive map. - Add repository citation metadata (
CITATION.cff) and adjust CI fast-tests workflow to run a dependency matrix.
Reviewed changes
Copilot reviewed 10 out of 17 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Major readme overhaul: workflow diagram link, archive schema/v2 docs, updated examples and API references. |
| examples/README.md | Updates example prerequisites and adds references to new parallel/timeseries/systematics notebooks. |
| docs/ux-review-feat-bouquet-class-api.md | Removes a large temporary UX review / planning document from docs/. |
| docs/flowchart/svg-pan-zoom.min.js | Adds vendored JS dependency used by the flowchart page for pan/zoom controls. |
| docs/flowchart/README.md | Documents the flowchart artifacts and how to regenerate them locally. |
| docs/flowchart/physics_workflow.svg | Adds a generated “physics workflow” SVG used in docs/README embedding. |
| docs/flowchart/l0_overview.svg | Adds a generated high-level stage overview SVG. |
| docs/flowchart/build.py | Adds the Graphviz renderer that produces the SVGs and a self-contained interactive HTML page. |
| docs/CI.md | Updates CI documentation to describe the pinned+latest fast-test matrix and branch protection guidance. |
| docs/CHANGES_SUMMARY.md | Adds a consolidated change-summary section for the class API + schema v2 round. |
| docs/archive-schema.md | Adds a human-readable schema v2 layout reference for the HDF5 archive. |
| CITATION.cff | Adds CITATION metadata for “Cite this repository” / tooling integration. |
| .github/workflows/tests.yml | Updates fast test workflow to run a pinned-vs-latest dependency matrix. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+279
to
+280
| # ...or hand the run object itself to any reader/plotter: | ||
| plot_bouquet(b) |
Comment on lines
+457
to
+458
| All plotting functions return `(fig, axes)` and accept a `Bouquet`, a | ||
| `BouquetArchive`, a bare header, or a `.h5` path interchangeably. |
Comment on lines
+24
to
33
| strategy: | ||
| fail-fast: false | ||
| matrix: | ||
| deps: [pinned, latest] | ||
| name: fast (${{ matrix.deps }}) | ||
| steps: | ||
| - uses: actions/checkout@v4 | ||
| - uses: actions/setup-python@v5 | ||
| with: | ||
| python-version: "3.13" |
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.
Docs refresh (PR-A scope)
README.md — full rewrite: fixed all 12 stale-API errors (the pre-refactor scan_value/discover_scan_values names, the nonexistent PFile.get()), corrected the citation to v0.2.0, added a CI badge, and added new sections for the archive/provenance (BouquetArchive, load_config), parallel generation, timeseries sweeps, and an updated perturbed-vs-fixed table reflecting the Zeff-primary density scheme. Every API name in it verified by introspection against the installed package.
New: CITATION.cff (GitHub "Cite this repository" support) and docs/archive-schema.md (the human-readable schema-v2 spec).
docs/CHANGES_SUMMARY.md — the ten decisions from the ux-review working doc folded in as a "2026-07 round" section; the working doc deleted as it instructed. CI.md and examples/README.md updated; gui-display-guide and the jphi-edge issue doc kept (auditors verified both still accurate).
CI: tests.yml now runs a pinned + latest dependency matrix, so the next scipy/numpy release breaks its own canary leg instead of your feature PRs.
Repo (already live, no commit needed): description + 8 topics set, GitHub Pages enabled serving /docs from main, homepage set to https://d-burg.github.io/bouquet/.
Logic flow map (PR-B scope) — docs/flowchart/
10 haiku-tier extraction agents mapped every subsystem → merged into graph.json: 552 nodes / 761 edges, every node typed (knob/quantity/transform/decision/artifact) and anchored to file:line. An adversarial verifier spot-checked 24 edges (22/24 correct, zero topology errors; the 2 metadata fixes applied), and a completeness critic added 13 missing gates (homotopy rollback, QP saturation, l_i-target sampling, the VSC in-spec metric, the SKIP_* diagnostic env gates). The extractors' one false negative (efit01_geqdsk "unused" — actually consumed via getattr) was hand-patched.
build.py renders it deterministically with graphviz: a stage-overview SVG (embedded in the README) and the full clustered map, packaged as a fully self-contained index.html with pan/zoom, node search, and hover tooltips. Verified in a live browser: zero console errors, search highlights (19 hits for "j_BS"), zoom controls active.
Verification: 187 tests pass, proprietary-reference scan clean, workflow YAML valid.