Skip to content

docs+feat: README discoverability, rvctool defaults, bdsim model CLI access - #47

Open
petercorke wants to merge 1 commit into
fix/notebook-erratafrom
docs/getting-going
Open

docs+feat: README discoverability, rvctool defaults, bdsim model CLI access#47
petercorke wants to merge 1 commit into
fix/notebook-erratafrom
docs/getting-going

Conversation

@petercorke

Copy link
Copy Markdown
Owner

Summary

Note: based on fix/notebook-errata (#45), not main -- retarget to main once that merges, since this branch was cut from its tip and the diff will stay clean once those commits land there.

Triggered by "how does a user find the notebooks/figures after pip install?" -- turned into a broader pass on README clarity, rvctool's prompt defaults, and actually making bdsim models runnable from a bare shell.

README:

  • Fix 3 broken links in "Additional book resources" (pointclouds, 3dfigures, examples all pointed at nonexistent top-level folders -- real paths are figures/pointclouds, figures/3d, RVC3/examples)
  • Move "Additional book resources" up to right after "Installing the package", instead of being the very last section of a 325-line file
  • Add a one-line pointer to that section right after the install instructions, and a top-of-file [!NOTE] banner linking errata.md
  • Rewrite "Block diagram models" to document all three ways to run a model (rvctool %run -i, the new rvc3-model command, bdsim_path to locate the install folder)

rvctool: replaced the confusing -n/--normal (dest="book", inverted sense) with a direct --book/--no-book pair. Defaults changed so a plain rvctool gives a nicer interactive experience (RVC3 >>> prompt, Out[N]: labels shown, ANSImatrix on, cwd to examples) rather than the old book-print-fidelity defaults; --book now narrowly means "match the printed page exactly" (plain >>> , no Out[N]:, no ANSI). Also fixes a real bug: book mode used to overwrite --prompt unconditionally even when explicitly passed, silently breaking the tool's own documented RVCTOOL_OPTIONS example.

New RVC3/models/__init__.py, RVC3/bin/__init__.py: both packages were implicit namespace packages (no __init__.py despite being explicitly listed in pyproject.toml's packages=[...]), which is why bdsim_path.py's own Path(models.__file__) crashed (namespace packages have __file__ = None). Restored bdsim_path.py from UNTRACKED/ -- it had existed there, uncommitted, for years; the pyproject.toml [project.scripts] entry pointing at it has never actually worked in any real install until now.

New rvc3-model command: runs a named model from RVC3/models/ directly from a bare shell, no rvctool/Jupyter session needed. Adds the models directory to sys.path first so sibling imports some models use still resolve. (Running it standalone against all models surfaced the missing-imports bug fixed in #46.)

Test plan

  • rvctool --test -- 6/6 checks pass
  • rvc3-model vloop_test and bdsim_path both work as installed console commands
  • Verified all internal README links resolve to real paths

…lts, bdsim model CLI access

README:
- Fix 3 broken links in "Additional book resources" (pointclouds,
  3dfigures, examples all pointed at nonexistent top-level folders --
  real paths are figures/pointclouds, figures/3d, RVC3/examples).
- Move "Additional book resources" up to right after "Installing the
  package", so "pip install gets you the library, clone the repo for
  notebooks/figures" isn't buried as the very last section of a
  325-line file.
- Add a one-line pointer to that section right after the install
  instructions, and a top-of-file [!NOTE] banner flagging this pass
  of fixes, linking errata.md.
- Rewrite "Block diagram models" to document all three ways to run a
  model (rvctool %run -i, the new rvc3-model command, bdsim_path to
  locate the install folder) instead of just one, and fix its own
  %run -m -> %run -i staleness.

rvctool: replace the confusing -n/--normal (dest="book", inverted
sense) with a direct --book/--no-book pair. Defaults changed so a
plain `rvctool` now gives a nicer interactive experience by default
(RVC3 >>> prompt, Out[N]: labels shown, ANSImatrix on, cwd to
examples) rather than the old book-print-fidelity defaults; --book
now narrowly means "match the printed page exactly" (plain '>>> ',
no Out[N]:, no ANSI). Also fixes a real bug: book mode used to
overwrite --prompt unconditionally even when explicitly passed,
silently breaking the tool's own documented RVCTOOL_OPTIONS example.
Removed the now-dead args.prompt is None branch in MyPrompt (prompt
always has a real default now).

New: RVC3/models/__init__.py, RVC3/bin/__init__.py -- both packages
were implicit namespace packages (no __init__.py despite being
explicitly listed in pyproject.toml's packages=[...]), which is why
bdsim_path.py's own Path(models.__file__) crashed (namespace packages
have __file__ = None). Restored bdsim_path.py from UNTRACKED/ (it had
existed there, uncommitted, for years -- the pyproject.toml
[project.scripts] entry pointing at it has never actually worked in
any real install until now).

New: rvc3-model command (RVC3/bin/rvc3_model.py) -- runs a named
model from RVC3/models/ directly from a bare shell, no rvctool/Jupyter
session needed. Adds the models directory to sys.path first so
sibling imports some models use (e.g. `from vloop import vloop, B`)
still resolve.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
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