Automatically update parameter tables in documentation

[samsrabin]

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.
• Something is annoying.

What part(s) of the documentation does this concern?

• Technical Note (science and design of the model)
• User's Guide (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 has PFTs in columns, but others have them in rows
• Decomposition: Decomposition rate constants 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, 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 would have to be broken up into 2 tables, one for low and one for high.
• Dust: Fraction, diameter, sd gives units of the parameters in the column headers... Might be a good idea everywhere.

[linniahawkins]

I like the idea of changing the table names to parameter 'long names' and including units. I think the tech note should be self consistent with CLM (not necessarily with the paper the parameterizations are based on).

I'm envisioning we have some consistent language used throughout the tech note like 'The initial implementation of this parameterizations used values from xyz et al., (***). Parameter uncertainty ranges were set per Kennedy et al., 2025 and values are regularly updated via calibration (see section 2. of tech note).' or something like that so we don't have to change any text when values in parameter tables are updated.