docs: correct rebalancing controls, sizing bounds and API descriptions - #147

Closes #145

Changes

Correct the rebalancing and configuration guides and the existing RebalanceMode, RebalanceConfig and TargetWeightExecutor.execute descriptions. Add their API destinations to the reference and link the guide directly to them.

• Select executor modes through RebalanceConfig.rebalance_mode. Distinguish the separate serialized BacktestConfig setting and broker helper.
• Describe when modes process eligible orders and refresh their sizing basis. Remove unsupported batch-fill guarantees, accuracy rankings and general framework-default claims.
• Explain that headroom scales requested weights and that a target cap applies before whole-share rounding. Signatures, defaults and executable behavior are preserved.

Behavior evidence

Native Backtrader 1.9.78.123 with $100,000 cash, three bars at $100 and order_target_percent(target=1.0) requested and filled 1,000 shares. The guide's claimed 0.998 default would have produced 998.

A real public Backtest Engine run with max_single_weight=0.25, whole shares, $100,000 equity and $150 prices filled 167 shares: $25,050 notional and 25.05% exposure. The corrected guide states that rounding can exceed the nominal target.

Both modified Python files have identical executable ASTs after removing docstrings. The diff changes descriptions only.

Validation evidence

Source-hash checks include docstrings, so the correctness records were regenerated through the existing producers at source commit 5c87d0c:

• Synthetic matrix: 66 required passes, two explicitly unsupported cases.
• Real strategies: all 17 Backtest output identity sets match the original measured outputs. The existing native outputs were reused and verified; none of those native engines was rerun.
• The existing source-certification command accepted the documented equivalence reason. Every performance record, timing sample and original measurement source identity remains unchanged. No timing was re-measured or relabeled.
• Full non-benchmark suite: 2,269 passed, nine opt-in native checks skipped, five benchmark tests deselected; global and critical coverage gates passed, 87.48% combined coverage.
• Executable documentation examples and 151 direct API-call checks passed. Strict MkDocs, 8,996 rendered links, 33 external destinations and all hooks passed.

Selected head 37b1a54 incorporates merged backend main 62adafa. Its src/, docs/ and validation/ bytes are identical to the locally qualified tree at 0a0d954. The refresh imports only the backend requirement already merged separately. Fresh strict docs, links, generated claims, hooks and rendered version/commit identity checks passed at this exact head. Applicable hosted checks and package qualification remain required before ordinary merge.

AI assistance

Codex inspected the producing implementation, reproduced the native and public Engine examples, corrected the prose, verified AST equivalence, regenerated correctness evidence and ran the existing timing-certification command and checks. Codex drafted this description. No independent human review or universal framework equivalence claim is asserted.

Release, tag, publication and deployment remain separate decisions.