lanl / lanl/PyBNF

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

Open
#765 0 comments 0 reactions 0 assignees View on GitHub

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 global max_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 as profile_likelihood_confidence, which a profile_likelihood run 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

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.