config_keys.rst has fallen behind the grammar: 64 of 200 accepted keys have no entry, and config.rst still presents it as the complete list
Nobody has claimed this yet.
- Dominant language
- Python
- Stars
- 25
- Forks
- 24
- Avg merge
- 2h 6m
- Merged PRs (30d)
- 95
Description
Summary
config.rst tells the reader where to find the keys they can set:
The available configuration keys to be specified are detailed in :ref:
config_keys.
Measured against the parser's own key lists (strkeylist, numkeys_int, numkeys_float,
multnumkeys, multstrkeys in parse.py), 64 of 200 accepted keys have no entry in
config_keys.rst. A reader who takes that sentence at face value will conclude those keys do
not exist.
This looks like accumulated drift rather than an editorial decision: the missing keys are
whole families added since the page was last swept — the profile-likelihood knobs, the
multiple-shooting knobs, the per-method gradient tolerances and budgets, the experimental-design
keys, and assorted others (sbml_atol, rhat_threshold, diagnostics_every,
output_noise_trajectory, outlier_method, precondition_adapt, neg_bin_r, ...).
The 8 that a search does not find in any prose page
Most of the 64 are documented on a topic page even though they are absent from the reference
index — gradient_fitting.rst covers the profile-likelihood and design families, for instance.
These eight are the ones with no literal mention in any .rst:
| key | default | where it is described today |
|---|---|---|
profile_likelihood_grad_tol |
1e-8 |
docstring only |
profile_likelihood_step_tol |
1e-8 |
docstring only |
profile_likelihood_max_iterations |
max_iterations |
docstring only |
design_confidence |
0.95 |
docstring only |
design_observables |
all measured observables | docstring only |
trf_max_iterations |
max_iterations |
prose, but only as <method>_max_iterations |
lbfgs_max_iterations |
max_iterations |
prose, but only as <method>_max_iterations |
gntr_max_iterations |
max_iterations |
prose, but only as <method>_max_iterations |
The last three are a reporting artifact worth recording: gradient_fitting.rst:174 says "For
all three, <method>_max_iterations caps the iterations per start and defaults to the global
max_iterations", which documents them correctly but under a placeholder, so a reader (or a
grep) looking for the literal key finds nothing. The first five have no prose coverage at all —
only module docstrings, which reach the rendered docs as a source view rather than as a page
anyone would read to learn the key exists.
Semantics for the five, from their docstrings, so the writing does not have to be re-derived:
profile_likelihood_grad_tol/_step_tol— the optimality and step tolerances of the inner
re-optimization and of the polish, shared by whichever inner optimizer the objective selects
(Trust-Region-Reflective or L-BFGS-B). Profiling deliberately exposes one pair rather than each
method's own.profile_likelihood_max_iterations— the per-start polish budget; runtime-guarded, so it is a
valid key but not a schema field, and defaults to the globalmax_iterations.design_observables— restricts candidate measurements to a named set of observables, for when
only some assays can be run; absent, every observable the fit already measures is a candidate.design_confidence— the confidence level of the predicted intervals in the design report;
same meaning asprofile_likelihood_confidence, which aprofile_likelihoodrun writing a
design report uses instead so both halves of its output are quoted at one level.
Expected
Bring config_keys.rst back in line with the grammar, so the sentence in config.rst is true
again. The check is mechanical and worth keeping: enumerate the parser's key lists, diff against
the page's **key** headings, and require the difference to be empty — a test would stop this
drifting a third time.
Where a key is already explained well on a topic page, the entry can be short and point there
rather than duplicate it; what matters is that every accepted key is findable from the reference.
Scope
docs/config_keys.rst, with a one-line consequence for docs/config.rst if the decision is ever
to make the page an index rather than a complete list.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the key lists in parse.py and the headings in docs/config_keys.rst, then compare them mechanically to identify every missing accepted key. Add reference entries for all 200 keys, pointing to topic pages where appropriate, and add a check that the parser lists and documentation headings stay in sync; update docs/config.rst only if the index wording changes.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 74/100