Skip to content

docs: trim the configuration page - #495

Merged
7174Andy merged 1 commit into
mainfrom
andrew/docs-trim-configuration
Sep 1, 2026
Merged

docs: trim the configuration page#495
7174Andy merged 1 commit into
mainfrom
andrew/docs-trim-configuration

Conversation

@7174Andy

@7174Andy 7174Andy commented Sep 1, 2026

Copy link
Copy Markdown
Collaborator

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

  • Full Configuration Examples (303 lines) 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 "Choosing a Configuration" 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, restating 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" — restated troubleshooting.md#reaching-the-allocator, which it already linked to.
  • "Use Your Own Research Software"adapting.md owns this.
  • The 70-line schema dump under Allocator Configuration. Every key and default is in the reference tables immediately below it; replaced with a section skeleton.

Removed as false

Section Claim Reality
Configuration System Env-var overrides via ENV_VAR, and command-line overrides No @hydra.main, no argv handling; get_config() calls compose() with no overrides. Neither exists.
Environment Variables Not Working Debug with echo $DB_PASSWORD Nothing reads DB_PASSWORD from the environment — it appears only inside a log string
Multiple GPU Types python main.py --config-name=config-gpu Same reason: not a Hydra app, so this does nothing

Configuration System now says what is true: edit the file, and CONFIG_DIR / CONFIG_NAME move which file is read.

Also dropped "Configuration Best Practices" (five generic bullets) and the two remaining Troubleshooting Configuration entries, which troubleshooting.md covers.

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:

    Scenario lablink-validate-config CLI validate_config
    IP Only [PASS] OK
    Let's Encrypt [PASS] OK
    CloudFlare [PASS] OK
    ACM + ALB [PASS] OK
  • Anchors: parsed every built page in site/ for links into configuration/#… and confirmed each resolves against the rebuilt page's heading ids — no missing anchors anywhere in the site. (Caught one on the way: ### ACM + ALB slugifies to acm-alb, not acm--alb.)

  • YAML: all remaining blocks validate against the Config dataclass; down from 19 blocks to 12.

  • Build: mkdocs build clean, same pre-existing griffe warnings as main.

Design Decisions

  • Base + overlay rather than deleting the examples. An operator wants a file to copy. Splitting into base + a dns/eip/ssl overlay 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.
  • Kept the section skeleton at the top. A reader landing on "Configuration Files" wants the file's shape immediately; a 17-line skeleton gives that without duplicating the reference tables underneath.
  • Left the reference tables completely alone. They're the page's job and eight other pages link into them. The trim is entirely prose, examples, and dead sections.

@7174Andy
7174Andy force-pushed the andrew/docs-trim-configuration branch from 11ad7ba to 7effe82 Compare September 1, 2026 23:24
Base automatically changed from andrew/docs-configuration-refresh to main September 1, 2026 23:32
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
7174Andy force-pushed the andrew/docs-trim-configuration branch from 7effe82 to 103c652 Compare September 1, 2026 23:32
@7174Andy
7174Andy merged commit fc757a0 into main Sep 1, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant