docs: trim the configuration page - #495
Merged
Merged
Conversation
7174Andy
force-pushed
the
andrew/docs-trim-configuration
branch
from
September 1, 2026 23:24
11ad7ba to
7effe82
Compare
1123 -> 758 lines. The page compared the same five scenarios in three different tables, and documented three mechanisms that do not exist. Removed as duplicated: - Full Configuration Examples was five complete configs in which 8 of 11 top-level sections were byte-identical; only dns, eip and ssl varied, which is exactly what the "Key Differences Between Examples" table below them tabulated and what the "Choosing a Configuration" table above them tabulated again. Now one base config plus a per-scenario overlay, with the three tables collapsed into one. - The four per-provider YAML snippets under SSL Providers, which restated those same scenarios a fourth time. - "Let's Encrypt Rate Limits", a second copy of the warning admonition 40 lines above it. Its two extra numbers moved into that admonition. - "Browser Access", which restated troubleshooting.md#reaching-the-allocator that it already linked to. - "Use Your Own Research Software", which adapting.md owns. - The 70-line schema dump under Allocator Configuration; every key and default is already in the reference tables directly below it. Replaced with a section skeleton. Removed as false: - "Configuration System" advertised environment-variable and command-line overrides. There is no @hydra.main and no argv handling anywhere in the allocator; get_config() calls compose() with no overrides, so neither works. Replaced with what is true: edit the file, and CONFIG_DIR / CONFIG_NAME move which file is read. - "Environment Variables Not Working" told the reader to check $DB_PASSWORD. Nothing reads DB_PASSWORD from the environment; it appears only inside a log string. - "Multiple GPU Types" ended with `python main.py --config-name=config-gpu`, which for the same reason does nothing. Also dropped "Configuration Best Practices" (five generic bullets) and the remaining two Troubleshooting Configuration entries, which troubleshooting.md covers. Verified: base + each of the four overlays composes to a config that passes both lablink-validate-config and the CLI's validate_config; every anchor into this page from every other built page still resolves. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01L2KHnDb7mbpcWQV72JeXQV
7174Andy
force-pushed
the
andrew/docs-trim-configuration
branch
from
September 1, 2026 23:32
7effe82 to
103c652
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Stacked on #494 — review that one first; this PR targets its branch, so the diff here is the trim alone.
Summary
1123 → 758 lines. Same treatment as the DNS page in #492: cut what was duplicated, cut what was false, leave the reference intact.
The page compared the same five scenarios in three separate tables, and documented three mechanisms that don't exist.
Removed as duplicated
dns,eipandsslvaried — which is exactly what the "Key Differences Between Examples" table below them tabulated, and what "Choosing a Configuration" above them tabulated again. Now one base config plus a per-scenario overlay, with the three tables collapsed into one.troubleshooting.md#reaching-the-allocator, which it already linked to.adapting.mdowns this.Removed as false
ENV_VAR, and command-line overrides@hydra.main, no argv handling;get_config()callscompose()with no overrides. Neither exists.echo $DB_PASSWORDDB_PASSWORDfrom the environment — it appears only inside a log stringpython main.py --config-name=config-gpuConfiguration System now says what is true: edit the file, and
CONFIG_DIR/CONFIG_NAMEmove which file is read.Also dropped "Configuration Best Practices" (five generic bullets) and the two remaining Troubleshooting Configuration entries, which
troubleshooting.mdcovers.Untouched
Every reference table other pages anchor into —
db,machine,dns,ssl,monitoring,manual, machine-type-options — plus the Cloudflare Tunnel walkthrough, AMI ID, and Deployment Identity.Testing
The examples actually work. Composed the base with each of the four overlays and ran both validators on the results:
lablink-validate-configvalidate_config[PASS][PASS][PASS][PASS]Anchors: parsed every built page in
site/for links intoconfiguration/#…and confirmed each resolves against the rebuilt page's heading ids — no missing anchors anywhere in the site. (Caught one on the way:### ACM + ALBslugifies toacm-alb, notacm--alb.)YAML: all remaining blocks validate against the
Configdataclass; down from 19 blocks to 12.Build:
mkdocs buildclean, same pre-existing griffe warnings asmain.Design Decisions
dns/eip/ssloverlay keeps that while removing the eight sections that were being maintained in five places — and the overlay is the comparison, so the diff table stops needing to exist separately.