Docs: Remove outdated doc

Author: VEZY

docs/make.jl

@@ -75,9 +75,8 @@ makedocs(;
             "Public API" => "./API/API_public.md",
             "Example models" => "./API/API_examples.md",
             "Internal API" => "./API/API_private.md",],
-        "Improving our documentation" => "documentation_improvement.md",
         "Developer guidelines" => "developers.md",
-        "Planned features" => "planned_features.md",
+        "Roadmap" => "planned_features.md",
     ]
 )
 

docs/src/developers.md

@@ -1,125 +1,114 @@
-# Developer guidelines
+# Developer Guidelines
 
-This page is intended for people who wish to contribute to PlantSimEngine, and indicates the various parts to bear in mind when adding in new code.
+This page is for contributors working on PlantSimEngine itself. It focuses on
+the local development workflow, the checks worth running before opening a pull
+request, and a few implementation details that are easy to miss.
 
 ## Working on PlantSimEngine
 
-Instructions are no different than for any other package. Use git to clone the repository [https://github.com/VirtualPlantLab/PlantSimEngine.jl](https://github.com/VirtualPlantLab/PlantSimEngine.jl).
+Clone the repository from
+[GitHub](https://github.com/VirtualPlantLab/PlantSimEngine.jl) and develop
+against a checked-out local copy, typically through `Pkg.develop(path="...")`.
 
-When testing your changes, your environement will need to use a command such as `Pkg.develop("PlantSimEngine")` to make use of your code.
+We mostly follow the Julia manual's
+[style guide](https://docs.julialang.org/en/v1/manual/style-guide/). Questions,
+bug reports, and design discussions should go through
+[GitHub issues](https://github.com/VirtualPlantLab/PlantSimEngine.jl/issues) or
+the related pull request.
 
-We work with VSCode and are most comfortable with that IDE for Julia development. We mostly follow the manual's [Julia style guide](https://docs.julialang.org/en/v1/manual/style-guide/)
+The [Roadmap](@ref) summarizes longer-term work that is not yet complete.
 
-Once you've made the necessary checks (see the [Checklist before submitting PRs](@ref) listed below), you’ll need to create your pull request and ask to be added to the contributors if you wish to submit new changes.
+## Local environments
 
-This documentation has a [Roadmap](@ref). The list of known issues and related discussions can be found [here](https://github.com/VirtualPlantLab/PlantSimEngine.jl/issues). Some are outdated, some are discussions related to potential features, but others are genuine bugs or enhancement suggestions.
+PlantSimEngine currently has three main local environments:
 
-Other details and questions can be posted on our issues page, or as part of your Pull Request.
+- `test/` for the package test suite and doctests run from `test/runtests.jl`;
+- `docs/` for the Documenter build;
+- `benchmark/` for benchmark scripts used to compare performance locally.
 
-## Quick rundown
+## Running checks locally
 
-### Testing environments
+### Main test suite
 
-PlantSimEngine has several developer environements:
+Run the standard test suite from the repository root:
 
-- `/PlantSimEngine/test`, to check for non-regressions
-- `/PlantSimEngine/test/downstream`, whose folder contains a few benchmarks on PlantSimEngine, PlantBioPhysics and XPalm, run as a Github Action, to ensure changes don't cause performance regressions in packages depending on PlantSimEngine. You’ll need to have a version of those packages accessible if you wish to test them locally. Those are distinct from the Github Action that does some integration checks to ensure no unexpected breaking changes occurs.
- `/PlantSimEngine/docs`, to build the documentation. The documentation runs code, and some of the functions' documentation for the API are also tested as `jldoctest` instances
+```julia
+julia --project=test test/runtests.jl
+```
 
-### Running the standard test suite
+Some tests exercise threaded execution, so it is worth running them with more
+than one Julia thread when validating parallel behavior.
 
-Simply execute the `/PlantSimEngine/test/runtests.jl` file in the test environment. Note that you'll need to start Julia with multiple threads for the multi-threading tests to successfully run.
+### Documentation
 
-You'll also need the companion packages PlantMeteo and MultiScaleTreeGraph, as well as other Julia packages such as DataFrames, CSV, Documenter, Test, Aqua and Tables.
+Build the documentation from the repository root with:
 
-### Downstream tests
+```julia
+julia --project=docs docs/make.jl
+```
 
-With XPalm and PlantBioPhysics properly instantiated, execute the `/PlantSimEngine/test/downstream/test/test-all-benchmarks.jl`. You may need to add some packages for the script to run locally.
+The docs environment includes the extra packages needed for examples and API
+documentation, such as `Documenter`, `CairoMakie`, `PlantMeteo`, and
+`MultiScaleTreeGraph`.
 
-### Building the documentation
+### Benchmarks
 
-In the `/PlantSimEngine/docs` environment, run `/PlantSimEngine/docs/make.jl`. It requires a couple of packages that aren't compulsory elsewhere (Documenter, CairoMakie, PlantGeom).
+Benchmark scripts live in `benchmark/`. They are useful when a change may alter
+runtime characteristics, but they are not a substitute for the main test suite
+or downstream integration checks.
 
-### Editing benchmarks
+## CI workflows
 
-⁃ If you wish for a branch to be benchmarked after every commit, then you need to declare it in the Github Action for benchmarks's yml file : [https://github.com/VirtualPlantLab/PlantSimEngine.jl/blob/main/.github/workflows/benchmarks_and_downstream.yml](https://github.com/VirtualPlantLab/PlantSimEngine.jl/blob/main/.github/workflows/benchmarks_and_downstream.yml) and add your branch to the `on: push:` section.
-⁃ You can view benchmarks here: <https://virtualplantlab.github.io/PlantSimEngine.jl/dev/bench/index.html>. They are still somewhat WIP and not yet battle-tested.
-⁃ You may occasionally need to update or delete a benchmark, in which case you will need to manually delete it in the **gh-pages** branch, in `dev/bench/index.html`
-⁃ The actual benchmark list is located in the `test/downstream` folder.
+The repository currently relies on these GitHub Actions workflows:
 
-## Things to keep an eye out for
+- `CI.yml` for the main test matrix, docs build, and coverage;
+- `Integration.yml` for downstream checks against packages that depend on
+  PlantSimEngine;
+- `Benchmarks.yml` for pull-request benchmark runs;
+- `register.yml` and `TagBot.yml` for release automation.
 
-### Check downstream tests
+If a change affects public APIs or execution behavior, check both `CI` and
+`Integration` before merging. Benchmark results are useful for regressions, but
+should be interpreted alongside the test results.
 
-⁃ If your changes affect the API, then they might affect a package depending on PlantSimEngine. Benchmarks can be a way to check, as some benchmarks run other packages. Otherwise, a specific GitHub action, [https://github.com/VirtualPlantLab/PlantSimEngine.jl/blob/main/.github/workflows/Integration.yml] runs other packages’ test suites. If this action fails, then it is likely some breaking change was introduced that hasn’t been accounted for in the downstream package. If you expected a breaking change and labelled your release as such, there will be no action failure
-⁃ Note that those tests don’t build the doc (iirc), so they don’t cover that.
-⁃ API changes can also affect downstream packages’ documentation and tests...
+## Documentation impact
 
-### Which documentation pages may be affected by changes
+Changes in PlantSimEngine often require documentation updates beyond the page you
+were editing.
 
-You may impact several specific documentation pages depending on what you changed. Features and API changes affect whatever they might affect, but there are some less obvious ramifications:
+- User-facing errors often require updates to the troubleshooting pages.
+- New examples should ideally become doctests or rendered examples.
+- API or behavior changes may require updates to the roadmap, migration notes,
+  and example pages.
+- If a feature remains experimental, say so clearly in the docs instead of
+  letting examples imply stable support.
 
-⁃ Improving user errors may impact the **Troubleshooting** page.
-⁃ Extra features might also expand the **Tips and workarounds** page, as well as the ‘implicit contracts’ page.
-⁃ Some experimental features might be worth documenting in the dedicated **API** page, once it's added
-⁃ The roadmap "**Planned features**" page needs updating
-⁃ Potentially, other pages such as the **Credits** page, **Key Concepts**, etc. If the API makes use of new Julia features or syntax, the **Julia basics** page is probably also worth updating.
-⁃ New examples are worth making doctests of.
+## Pull request checklist
 
-### Previewing documentation
+- Make sure the change is covered by tests.
+- Run the main test suite locally.
+- Build the documentation locally if docstrings, examples, or APIs changed.
+- Review the affected docs pages and update them in the same pull request.
+- Check GitHub Actions after pushing.
+- If the change is breaking or deprecates an old path, document the migration
+  path before merging.
 
-You can preview generated documentation (assuming it was able to build) relating to your PR (example given with #128) by checking the related link: [https://virtualplantlab.github.io/PlantSimEngine.jl/previews/PR128/](https://virtualplantlab.github.io/PlantSimEngine.jl/previews/PR128/)
+## Implementation notes
 
-## Checklist before submitting PRs
+### Generated models and `eval`
 
-⁃ Ensure your code, uh, works
-⁃ Ensure your major changes are covered by some tests, and new features are documented
-⁃ Run the PlantSimEngine test suite locally and check errors
-⁃ Check on Github which issues it affects, and update/comment those issues, or link them to your Pull Request
-⁃ Check which doc page changes are needed (roadmap, … see further up), and update those
-⁃ Build the PSE doc and update whatever doc tests were broken
-⁃ Push your commit, and let the Github Actions run their course
-⁃ Check the 'CI' GitHub action and fix if necessary
-⁃ Check downstream and benchmark GitHub actions:
-    - If benchmarks tanked, then fix your code. If you need to add/update/delete benchmarks, do so.
-    - If you broke an integration/downstream test, you’ll need to investigate it
-    - If API changes were made, also check downstream packages’ documentation
+Some multiscale helpers generate model definitions dynamically so that status
+vectors can be converted into runtime-compatible mappings. This currently relies
+on `eval()`, which means some changes only become visible again after returning
+to top-level scope.
 
-It’s probably now safe to request a merge.
+The relevant code lives in `src/mtg/mapping/model_generation_from_status_vectors.jl`.
+If you touch that area, be careful about world-age issues and about tests that
+intentionally split setup and execution into separate top-level calls.
 
-### A few extra things worth doing
+### Coverage gaps to keep in mind
 
-⁃ You may have some new known issues, some remaining TODOs, document those somewhere, whether in the PR comments or in their own issue, make sure some trace remains
-⁃ Finally, update this page and this checklist: If a doc page is added, it may be part of the list of pages you need to keep an eye on. If proper memory allocation tracking and type stability checking is implemented, then that’ll need to be added to the list of things to check prior to a release, etc.
-
-### Other helpful things
-
-⁃ In the `/PlantSimEngine/test` folder, there are a few basic helper functions. One of them outputs vectors of ModelMapping, weather data, and output variables, which are used as a test bank/matrix for some tests, and provides wide coverage. If you wrote new models, new combinations of models, or added some new weather data, it helps to add them to the banks.
-⁃ New downstream packages are worth adding to the integration and downstream package registry.
-⁃ Unusual corner-cases are worth giving their own unit tests. Newly fixed bugs as well, even if the fix is fairly trivial.
-
-## Noteworthy aspects of the codebase
-
-### Automatic model generation
-
-A specific feature requires generating models on the fly, to enable passing vectors to `Status` objects in multi-scale simulations. There may be more features that wish to generate models.
-
-The solution makes use of a somewhat brittle feature, `eval()`, with some subtleties. You can read more about the related world age problem [here](https://arxiv.org/abs/2010.07516), or [here](https://discourse.julialang.org/t/world-age-problem-explanation/9714/15).
-
-The related file is `model_generation_from_status_vectors.jl`, which has some additional comments.
-
-What is important to bear in mind, is that if you call functions which generate models via `eval()`, you will need to return to top-level scope for those changes to become visible. You can see an example in `tests/helper_functions.jl` with the functions `test_filtered_output_begin` and `test_filtered_output`. The first function calls `modellist_to_mapping`, which creates some models on the fly to convert status vectors between a ModelList and its equivalent pseudo-multiscale mapping. The function is split in two so that it is possible to return to global scope and make the `eval()` changes publicly available. The second function then is able to run the simulations on the mapping with its generated models, and complete the test successfully.
-
-The errors returned by an `eval()`-related issue are very specific, and indicate that a generated model with an UUID suffix does not exist in the Main module, or something along those lines.
-
-There may be a better approach that avoids those pitfalls, but that's what we have for now. Be cautious when calling functions from that file, and make sure to look out for comments indicating a function was split into two.
-
-### Weather/timestep/status combinations
-
-Not all combinations of weather data structure/weather dataset size/status sizes combinations are tested in PlantSimEngine itself. Some are tested in PlantBioPhysics and XPalm. It'd be good to have those structures tested in PSE in the future, but for now it is highly recommended checking those packages' tests when changing the API.
-
-### Test banks
-
-They were briefly mentioned earlier in the page, but the test banks to increase the number of combinations tested for in terms of weather data, modellists/mappings and tracked outputs, could definitely be improved upon.
-
-Some additional work and tests regarding tracking memory allocations, type stability etc. would also be worth implementing/documenting.
+Not every combination of weather structure, status shape, mapping layout, and
+downstream usage is covered directly in PlantSimEngine. When changing the public
+API or runtime semantics, treat downstream integration results as part of the
+validation surface, not as optional extra signal.

docs/src/documentation_improvement.md

@@ -1,7 +1,11 @@
-# Help improve our documentation !
+# Help Improve The Documentation
 
-One goal for PlantSimEngine is to ensure testing ecophysiological hypotheses, or building plant simulations is as easy as can be for a wider range of people than previous frameworks.
+Good documentation is essential if PlantSimEngine is meant to stay usable for
+both new users and contributors.
 
-Good documentation is essential for that purpose.
+If a page is unclear, incomplete, or out of date, the preferred way to report it
+is to open an issue or submit a pull request on
+[GitHub](https://github.com/VirtualPlantLab/PlantSimEngine.jl/issues).
 
-If parts of the documentation are unclear to you, you are very welcome to send a PR, an email, or a message (either [on Github](https://github.com/VirtualPlantLab/PlantSimEngine.jl/issues) or [on the FSPM Discourse](https://fspm.discourse.group/latest)) so that we can improve upon it.
+Documentation fixes do not need to be large. Small corrections, clarified
+examples, and reports of missing release notes are all useful contributions.