Trim remote_build_layout.py prose (275 → 122 lines)

[bdraco]

What does this implement/fix?

remote_build_layout.py had a 47-line module docstring, an
89-line data_dir method docstring, and constant-block
comments that paraphrased what the values already convey. Per
CLAUDE.md's docstring rule: consumer-facing, no padding with
rationale. Trim aggressively.

275 → 122 lines (−55%), zero code changes.

What was cut

• Module docstring: dropped the three-consumer enumeration
  (it's a one-line pointer to the accessors now) and the
  "why a shared module" rationale. That argument belongs in
  the commit history of the module's introduction, not in
  every read of the file.
• data_dir: dropped the per-mode walk-through (default /
  addon / ESPHOME_DATA_DIR env override — same fallback
  chain documented on CORE.data_dir), the "why pin
  ESPHOME_DATA_DIR at all" section (paraphrase of the
  per-dashboard isolation point made elsewhere), and the
  cleanup-asymmetry follow-up note (belongs in an issue, not
  a docstring readers hit on every IDE hover).
• subtree / bundle: dropped the per-consumer
  enumeration. The path each returns is self-evident from
  the body.
• Module-level constants: stripped each block to the
  non-obvious bit (the leading-dot hides it from ls; the
  POSIX parts are pre-split because configuration paths are
  forward-slash on every platform; the bundle is outside the
  extract target because of prepare_bundle_for_compile).
• parse_from_configuration: dropped the reverse-engineering
  of the layout shape inside the docstring; the function body
  shows it directly.

What stayed

The non-obvious why's that don't have an obvious home
elsewhere:

• data_dir's per-dashboard scope: toolchain warmth across
  submits + Isolate receiver-side remote builds under per-build ESPHOME_DATA_DIR #578 basename-collision isolation.
• data_dir lives under CORE.data_dir rather than
  config_dir: the multi-GB artefacts belong on /data (the
  addon's per-instance volume), not the user's /config HA
  mount.
• BUNDLE_SUFFIX's "sibling, not child" placement vs the
  upstream pre-extract wipe (PR Fix Bundle file not found on every remote-build submit #552).

Behaviour preservation

Docstring + comment edits only — zero functional changes.
3176 tests pass; ruff + mypy clean.

Related issue or feature (if applicable):

• Follow-up to the doc-cross-references update on Split remote_build controller into Offloader + Receiver siblings #637; this
  is the same author's pass on a single file flagged for the
  same "text wall" issue.

Types of changes

• Bugfix (non-breaking change which fixes an issue) — bugfix
• New feature (non-breaking change which adds functionality) — new-feature
• Enhancement to an existing feature — enhancement
• Breaking change (fix or feature that would cause existing functionality to not work as expected) — breaking-change
• Refactor (no behaviour change) — refactor
• Documentation only — docs
• Maintenance / chore — maintenance
• CI / workflow change — ci
• Dependencies bump — dependencies

Frontend coordination

• No frontend change needed
• Companion frontend PR: esphome/device-builder-dashboard-frontend#

Checklist

• The code change is tested and works locally.
• Pre-commit hooks pass (ruff, codespell, yaml/json/python checks).
• Tests have been added or updated under tests/ where applicable.
• components.json has not been hand-edited (regenerate via script/sync_components.py if a sync is needed).
• Architecture-level changes are reflected in docs/ARCHITECTURE.md and/or docs/API.md.

[codspeed-hq]

Merging this PR will not alter performance

✅ 12 untouched benchmarks

---

_{Comparing trim-remote-build-layout-prose (ce53dcc) with main (c2c90df)}

[codecov-commenter]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 99.24%. Comparing base (58d78d8) to head (ce53dcc).
⚠️ Report is 3 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #643      +/-   ##
==========================================
+ Coverage   99.22%   99.24%   +0.01%     
==========================================
  Files         103      103              
  Lines       11097    11097              
==========================================
+ Hits        11011    11013       +2     
+ Misses         86       84       -2     

Flag	Coverage Δ
py3.12	99.21% <ø> (+0.01%)	⬆️
py3.14	99.24% <ø> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...home_device_builder/helpers/remote_build_layout.py	100.00% <ø> (ø)

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[Copilot]

Pull request overview

This PR trims documentation in helpers/remote_build_layout.py to reduce large docstrings/comments while keeping the file as the canonical description of the receiver-side remote-build on-disk layout.

Changes:

• Replaced the long module docstring with a shorter description of the remote-build layout and the RemoteBuildPath/parse_from_configuration entry points.
• Shortened docstrings for RemoteBuildPath.subtree(), .bundle(), .data_dir(), and parse_from_configuration().
• Reduced module-level constant comments to focus on only the non-obvious details.