Skip to content

feat(cli): add rich markdown style, refine docs - #266

Merged
Emin017 merged 26 commits into
mainfrom
emin/update-cli-docs
Sep 8, 2026
Merged

feat(cli): add rich markdown style, refine docs#266
Emin017 merged 26 commits into
mainfrom
emin/update-cli-docs

Conversation

@Emin017

@Emin017 Emin017 commented Sep 8, 2026 •
edited
Loading

Copy link
Copy Markdown
Member

What Changed

  • Render Typer help with Rich Markdown, expand long-form help for common commands, and add shell completion.
  • Add ecc doc <config|ug|tutorial|dev> with English and Chinese guides, byte-exact --plain output, and a styled pager for interactive terminals.
  • Ship all eight CLI guides in wheel and PyInstaller artifacts. Repair links after moving the guides into package data and extend artifact smoke tests.
  • Lazy-load plotting helpers so normal CLI, help, and doctor paths do not import Matplotlib. Stop collecting the host libfontconfig in the PyInstaller bundle.
  • Add regression tests for help rendering, docs, completion, packaged guides, lazy imports, and GitHub Actions color handling.

Scope

Select the areas touched by this PR:

  • CLI - command behavior, Typer command surface, output formats, or workspace commands.
  • Flow/runtime - workspace lifecycle, EngineFlow, step execution, logs, metrics, or artifacts.
  • EDA integration - Yosys, ECC-Tools, DreamPlace, KLayout, PDKs, or native/runtime wrappers.
  • Build/package - Nix, PyInstaller, wheels, uv.lock, or release artifacts.
  • CI/release - GitHub Actions, version checks, changelog, or release automation.
  • Tests/docs only

Runtime And Packaging Impact

  • No runtime or packaging impact
  • CLI output or machine-readable contract changed
  • Workspace layout, flow state, or artifact paths changed
  • Native toolchain or wrapper behavior changed
  • ecc-tools or ecc-dreamplace dependency changed
  • PyInstaller, Nix, or release artifact changed

Notes:

  • CLI help now uses Rich Markdown. This PR also adds ecc doc and shell completion; existing machine-readable output contracts are unchanged.
  • The bilingual CLI guides are now package data and are included in wheel and PyInstaller artifacts.
  • Plotting helpers are loaded only when requested, keeping Matplotlib and fontconfig out of normal CLI startup paths.
  • No dependency or submodule changes.

Validation

List the commands you ran. Mark checks that are not applicable as N/A.

  • uv run pytest test/
  • uv run ruff check chipcompiler test
  • uv run ruff format --check chipcompiler test
  • PyInstaller smoke: ecc --help, ecc --version, ecc version --json
  • Nix smoke: nix run .#cli -- --help
  • Manual flow smoke: N/A
  • Other: targeted CLI and packaging tests (138 passed); CI-mode CLI suite (1,094 passed, 2 deselected); packaged ecc doc smoke for English and Chinese guides.

Skipped checks and reason:

  • The exact full local uv run pytest test/, Nix smoke, and manual flow smoke were not run. The GitHub Actions Test job is still running; lint, commit-message, version, and PyInstaller jobs have passed.

Checklist

  • I kept the change scoped to ECC.
  • I updated docs or user-facing CLI text where behavior changed.
  • I included lockfile or version metadata updates when dependencies changed.
  • I documented any submodule updates and why they are needed.
  • I did not include local caches, virtual environments, or generated build outputs.
  • I explained skipped validation and remaining risk.

@Emin017 Emin017 added the enhancement New feature or request label Sep 8, 2026
@Emin017 Emin017 added this to the 0.1.0-alpha.12 milestone Sep 8, 2026
@Emin017
Emin017 force-pushed the emin/update-cli-docs branch from 7163c9a to 263806f Compare September 8, 2026 02:57
@Emin017
Emin017 force-pushed the emin/update-cli-docs branch from 1f5842a to ecfd5cd Compare September 8, 2026 04:00
@Emin017 Emin017 mentioned this pull request Sep 8, 2026
Merged
25 tasks
Yell-walkalone
Yell-walkalone previously approved these changes Sep 8, 2026
View reviewed changes
Base automatically changed from yell/update_cli to main September 8, 2026 09:25
@Emin017
Emin017 dismissed Yell-walkalone’s stale review September 8, 2026 09:25

The merge-base changed after approval.

Emin017 added 19 commits September 8, 2026 17:25
@Emin017
refactor(cli): drop direct click usage from the typer app
381dcb0 
Typer has vendored click since 0.26, so application code should go
through typer's re-exports instead of importing click itself:

- click.echo -> typer.echo
- the layout-image failure now prints the same "Error: ..." line via
  typer.echo(err=True) and raises typer.Exit(1) instead of
  click.ClickException
- invoke_typer_app runs the command in standalone mode and converts
  SystemExit back into an int return code, replacing the non-standalone
  click exception plumbing; click.Ctrl-C aborts are now handled by
  click ("Aborted!", exit 1) instead of propagating as a traceback
@Emin017
refactor(cli): unify typer app construction in a shared factory
f46d18b
@Emin017
test(cli): parse ast in the shared-factory invariant
1375650
@Emin017
feat(cli): render command help in markdown mode
ddd3293
@Emin017
fix(cli): keep angle-bracket placeholders in markdown help
b534abb
@Emin017
docs(cli): add long markdown help for high-frequency commands
c6d4ec1
@Emin017
docs(cli): fix docstring fidelity and narrow-width help rendering
9c76763
@Emin017
feat(cli): add ecc doc command for bundled guides
b202e3c
@Emin017
fix(cli): keep doc output byte-exact and encoding-safe
88ad4ba
@Emin017
fix(cli): keep doc section slices byte-exact
0921ebd
@Emin017
docs(guides): document ecc doc in the user guide
4c0a536
@Emin017
docs(guides): add doc to the command overview
a39bc88
@Emin017
fix(packaging): collect rich unicode data modules in the bundle
6ed6c9a
@Emin017
feat(cli): add ecc doc --sections topic index
6763bc4
@Emin017
fix(cli): keep heading parsing on one line and pin doc sections contract
23096ad
@Emin017
fix(packaging): stop bundling host libfontconfig in the bundle
fefbb2f
@Emin017
refactor(utility): lazy-load plot helpers to keep matplotlib off CLI …
e85a2a1 
…startup

chipcompiler.utility imported matplotlib.pyplot at package import time, so
every 'ecc' invocation (even --help) paid ~0.8s of matplotlib import and, in
the PyInstaller bundle with a cold font cache, spawned fc-list against the
host fontconfig config.

Re-export the five plot helpers via a PEP 562 module __getattr__ so
matplotlib is only imported when a plot function is actually used. Call
sites (already function-level imports in tools/ecc/plot.py) are unchanged.
@Emin017
fix(utility): keep lazy plot exports typed, discoverable, and regress…
a0dfdba 
…ion-tested

Address codex review of ee9df80:

- Move the PEP 562 __getattr__ behind a TYPE_CHECKING/else branch so
  pyright keeps rejecting unknown chipcompiler.utility attributes instead
  of accepting them via the inferred Any return.
- Add __dir__ so the five lazy plot names stay in dir()/help()/completion
  without importing matplotlib.
- Add fresh-process regression tests asserting that importing
  chipcompiler.utility and rendering 'ecc --help' leave matplotlib
  unloaded, and that the plot exports resolve on demand.
@Emin017
refactor(cli): simplify ecc doc to full-guide output with terminal pager
cd2063e 
Drop the SECTION argument and --sections topic index: ecc doc now always
shows the whole guide. Rendered output opens in the pydoc pager ($PAGER,
falling back to less/more) on a terminal and prints in full when piped;
--plain keeps its byte-exact output unpaged for scripts and agents.

Also stop forcing terminal mode on colorless streams in render_markdown:
rich 15 emits ANSI escapes when force_terminal=True even with no_color
set, so piped rendered output leaked escape codes.
@Emin017
fix(tools-ecc): keep matplotlib off non-plot CLI paths such as ecc do…
e7f3a98 
…ctor

Codex re-review found two remaining eager edges: runner.py imported
ECCToolsPlot at module top (pulled in by the package __init__), and the
tools.ecc package re-exported ECCToolsPlot eagerly, so 'ecc doctor' still
imported matplotlib via chipcompiler.tools.ecc.utility.

- Move the runner's ECCToolsPlot import into run_analysis, its only use.
- Re-export ECCToolsPlot from the package lazily (same PEP 562 pattern as
  chipcompiler.utility).
- Isolate MPLCONFIGDIR with tmp_path in the lazy-plot regression tests and
  extend them to cover the tools.ecc probe-import path.
@Emin017
feat(cli): keep rich highlighting inside the ecc doc pager
7395fcf 
console.pager() flattened all styles, so the paged guide lost every
heading and emphasis. Page with styles=color instead and default
LESS=FRX when the user has no LESS of their own: pydoc spawns plain
less, which escapes ANSI sequences unless -R is given.
@Emin017
feat(cli): ship the ecc doc guides inside the wheel
b4d9e5e 
Move the eight CLI guides from the repo-root docs/ into
chipcompiler/docs/ so uv_build includes them in the wheel; only files
under the module directory are packaged. guides_root() now resolves
them through importlib.resources, which covers dev checkouts, editable
installs, and wheel installs with one path; the _MEIPASS branch still
serves the PyInstaller bundle.

Relative links in the guides, docs/index.md, and the PyInstaller spec
datas are updated for the new location.
@Emin017
fix(cli): repair moved guide links and pin doc packaging contracts
b03d722 
Codex review of dc83f23 found relative links that never pointed
through ../ and were missed by the move (docs/examples/gcd,
docs/specification, workspace-cli.md, review-guidelines.md), now
resolved as ../../docs/... from chipcompiler/docs/.

Add artifact-level guards: a packaging test builds the wheel and
asserts all eight guides are inside, and the PyInstaller bundle smoke
test in CI now runs ecc doc for an English and a Chinese guide.
@Emin017
feat(cli): enable shell completion via --show-completion
9e24109 
Turn on typer's built-in completion options on the root app and let
completion requests through the empty-argv help shortcut, since they
carry their arguments in _ECC_COMPLETE/COMP_WORDS env vars instead of
argv. Document eval "$(ecc --show-completion)" in the en/cn guides,
noting the --install-completion caveat on NixOS-style managed rc files.
@Emin017
docs(cli): collapse exhaustive param listings in the config guide
1be57d6 
Section 15 repeated one 'ecc param set KEY VALUE' line for every tunable
field (86 for place.*, 24 for floorplan.*), duplicating what 'ecc param
list --step STEP' already prints. Keep a few representative examples per
step and defer the full enumeration to the CLI; the field tables in
sections 2-14 remain the complete reference.
@Emin017
test(cli): stabilize help rendering under CI
e13fbd4
@Emin017
Emin017 force-pushed the emin/update-cli-docs branch from ecfd5cd to e13fbd4 Compare September 8, 2026 09:25
@Emin017
Emin017 merged commit ce19438 into main Sep 8, 2026
5 checks passed
@Emin017
Emin017 deleted the emin/update-cli-docs branch September 8, 2026 09:50
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@Yell-walkalone Yell-walkalone Yell-walkalone left review comments

Assignees

No one assigned

Labels

enhancement New feature or request

Projects

None yet

Milestone

0.1.0-alpha.12

Development

Successfully merging this pull request may close these issues.

2 participants

@Emin017 @Yell-walkalone