Skip to content

Docs still describe deleted cli.py + _bin/ layout (followup to #7/#9) #11

Description

@zackees

Doc drift after #7

Same root cause as #9 (which I just closed) — packaging refactor #7 left stale references in artifact-walking tools. #9 fixed the runtime-test + CI-gate cases. This issue covers the documentation cases. Same failure shape as fbuild#748: the wheel-build path is correct but downstream readers (humans + agents + linters) see a description of a layout that no longer exists.

git grep -n '_bin\|cli\.py\|template_python_rust_cmd\.cli' \*.md \*\*/\*.md finds:

  • README.md:46-47 — tree diagram shows cli.py and _bin/ as part of the package layout. Both deleted in fix(install): ship template-cli as raw wheel script; drop Python shim #7.
  • README.md:95 — describes "`fbuild` console script, staged into `src/template_python_rust_cmd/_bin/`". Stale on both counts.
  • CLAUDE.md:79,85 — "The Python CLI shim in `src/template_python_rust_cmd/cli.py` stays thin" + "The release pipeline stages the compiled `template-cli` binary into `src/template_python_rust_cmd/_bin/`". Both gone.
  • ENHANCE.md:37 — "The Python CLI shim in `src/template_python_rust_cmd/cli.py` stays tiny". Gone.
  • crates/template-cli/README.md:5 — "staged into `src/template_python_rust_cmd/_bin/` by `ci/build_wheel.py`". Gone.
  • docs/ARCHITECTURE.md:9 — "packaged at `template_python_rust_cmd._bin/`". Gone.
  • docs/ARCHITECTURE.md:66 — "CLI shim that finds and execs the packaged native binary (`cli.py`)". Gone.
  • docs/RELEASE.md:18 — "`src/template_python_rust_cmd/_bin/`, drives maturin to produce". Gone.

Why this matters

A downstream consumer reading any of these files gets a description of how the binary used to be packaged. The actual mechanism (raw wheel script at <name>-<ver>.data/scripts/) is described correctly in src/template_python_rust_cmd/README.md and the comments in ci/build_wheel.py, but the top-level entry points (README.md, CLAUDE.md, docs/ARCHITECTURE.md) still describe the dead shape. Agent docs are particularly load-bearing here — CLAUDE.md is the routing document for any agent doing work in this repo.

Fix

Replace every cli.py / _bin/ reference with the actual current shape:

  • The package no longer has a CLI shim. template-cli[.exe] is installed directly into the venv's Scripts/ / bin/ by pip via the wheel's <name>-<ver>.data/scripts/ raw-script mechanism. See src/template_python_rust_cmd/README.md for the full rationale.
  • The build pipeline: ci/build_wheel.py builds template-cli via cargo, then post-processes the maturin-emitted wheel to inject the binary at <name>-<ver>.data/scripts/ and update RECORD.
  • Where docs explicitly say "two consumption stories: Python in-process API + CLI command", that's still right — but the CLI story is now "template-cli on PATH after install", not "Python shim that subprocess-launches a packaged binary".

Acceptance

grep -rn '_bin\|template_python_rust_cmd\.cli\|cli\.py' README.md CLAUDE.md ENHANCE.md docs/ crates/template-cli/README.md returns either:

  • no matches, OR
  • only historical context (e.g., a CHANGELOG entry explaining the migration).

Refs #7 (refactor that caused it), #9 (tests + gate cleanup), fbuild#748 (same failure shape).

Metadata

Metadata

Assignees

No one assigned

    Labels

    documentationImprovements or additions to documentation

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions