Automatically update parameter tables in documentation
- Dominant language
- Fortran
- Stars
- 352
- Forks
- 361
- Avg merge
- 2d 21h
- Merged PRs (30d)
- 7
Description
### What sort(s) of documentation issue is this?
- [ ] Something is missing.
- [ ] Something is (or might be) incorrect or outdated.
- [ ] Something is confusing.
- [ ] Something is broken.
- [x] Something is annoying.
### What part(s) of the documentation does this concern?
- [x] [Technical Note](https://escomp.github.io/CTSM/tech_note/index.html) (science and design of the model)
- [ ] [User's Guide](https://escomp.github.io/CTSM/users_guide/index.html) (using the model and related tools)
- [ ] Somewhere else (e.g., README file, tool help text, or code comment): _Please specify_
- [ ] I don't know
### Describe the issue
There are many tables throughout the Tech Note that contain parameter values from our parameter file. It is very annoying to have to keep these up to date, and the process is error-prone. It would be better to automate this.
### Additional context (optional)
Some initial thoughts:
- Each table in the documentation should just be an embed of a Markdown or rST file with the table—a "table file". A header should contain the file to be read and the parameters to be included. Maybe just include the `query_paramfile` command, actually.
- A GitHub Workflow should trigger whenever the `clm6_0` default parameter file changes. (As well if `query_paramfile` is touched.) It should:
1. Regenerate each of the tables using the updated parameter file.
2. Compare each table it generates to the tables in `doc/source/`.
3. Upon finding diffs in any table, post a comment on the PR with the new contents of each table file. (I think it would be possible to have the action auto-commit the changes, but that's scary.)
- Might be good for `query_paramfile` to have an option to ignore non-simulated crops, so we don't have those in every table.
2026-04-10 13:48 MDT: I'm going to have a think on this during today's documentation hackathon; will probably update this issue description with more notes.
After having gone through some of the Tech Note pages (alphabetically by file name, I'm through `CLM50_Tech_Note_Dust.html`):
- Need to think about parameter column titles. Some use something like a long name, others use equations like $a_1$, others might use raw parameter names. We might have to be okay with just using either variable name or `long_name` attribute.
- [Crops and Irrigation: Crop phenology and morphology parameters](https://escomp.github.io/CTSM/tech_note/Crop_Irrigation/CLM50_Tech_Note_Crop_Irrigation.html#id21) has PFTs in columns, but others have them in rows
- [Decomposition: Decomposition rate constants](https://escomp.github.io/CTSM/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.html#id3) is really weird... Might not survive the CLM6 rewrite, but still. Makes ya think. **Keep in mind that we don't have to implement this completely on the first go. If we want to, say, just tackle the PFT-level parameter tables at first, that'd still be a big improvement.**
- Some tables, e.g. [Decomposition: Respiration fractions](https://escomp.github.io/CTSM/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.html#id4), have footnotes. These would presumably just not be possible with an automated implementation, or at least would require some extra header material and infrastructure to process it.
- [Decomposition: Tillage decomp scalars](https://escomp.github.io/CTSM/tech_note/Decomposition/CLM50_Tech_Note_Decomposition.html#id7) would have to be broken up into 2 tables, one for low and one for high.
- [Dust: Fraction, diameter, sd](https://escomp.github.io/CTSM/tech_note/Dust/CLM50_Tech_Note_Dust.html#id1) gives units of the parameters in the column headers... Might be a good idea everywhere.
Contributor guide
Assessment
This issue has not been assessed yet.