docs: build a Bonito website and simplify modeling guides - #214
Merged
Conversation
Use DocumenterBonito with a botanical homepage, the original PlantSimEngine logo, and a matching light/dark palette. Keep the new dependencies in the documentation environment and document local builds. Normalize nested page paths for search and finish static exports with working asset, anchor, and preview-version URLs. Check exported pages and session assets before deployment. Validation: 120 documentation checks passed; 79 pages and states verified; 1,421 fragment links resolved; all 67 navigation pages indexed. Browser checks covered search, API links, version navigation, light/dark themes, and the interactive graph.
Organize the Bonito manual around coupling existing models and writing new ones, with runnable examples, explicit scientific assumptions, and practical guidance for AI coding agents. Consolidate duplicate introductions and downstream testing guidance, and remove completed design plans, audits, and handoffs rather than preserving a separate archive. Correct the teaching examples' radiation units and cumulative carbon accounting, preserve generated code/table rendering, and improve narrow-screen navigation. Keep only source files needed to build and validate the manual.
VEZY
changed the title
Use plain English throughout the manual, simplify the first results table with collect_outputs and sink, and replace verbose CompositeModel dumps with a bounded summary. Validation: 41 display checks, full executable documentation build, and 1212 internal fragment links passed.
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.
This replaces
Documenter.HTMLwithBonito.DocumenterBonitoand makes the manual easier to enter from a scientific modeling task. It follows the documentation website direction explored in #69, using Bonito without a separate Node/VitePress build step.The homepage explains where PlantSimEngine fits in plant and crop modeling, with 2D/3D examples, the botanical logo, and concrete guidance for AI-assisted work. The manual now has separate Couple models and Write models paths, with installation and a first simulation up front, followed by progressively deeper guides.
The manual is reduced from 79 to 58 pages. Duplicate introductions are consolidated, and nine completed design plans, audits, and handoffs are deleted. Lasting explanations remain in the guides, API reference, and tested examples; the agent skill remains part of the repository. No temporary planning archive or logo explorations are kept.
The revised examples explain their assumptions and units, show actual results and plots, and cover observed inputs, model replacement, per-object state, timing, and growth. The MAESPA-style teaching example now converts PAR energy to photon flux and allocates each cumulative carbon increment only once, with focused regression coverage. These remain illustrative examples, not calibrated biological models.
Documentation export adjustments handle nested assets and anchors, preview version navigation, search, embedded graphs, and generated code blocks/tables. The theme also works on narrow screens. Bonito 5.2 and Julia 1.11+ are required by the docs environment; package runtime dependencies and Julia compatibility are unchanged. The site is a static export: rerunning Julia simulations requires an execution backend.
Validation
git diff --checkpasses.The full package and downstream test suites were not rerun locally for this documentation update. Hosted previews and CI checks are handled by GitHub Actions.