Skip to content

fix(workspace): correct README architecture/style claims, add docs.rs feature badges - #499

Merged
matanlurey merged 1 commit into
mainfrom
docs/readme-accuracy
Jul 26, 2026
Merged

matanlurey merged 1 commit into
mainfrom
docs/readme-accuracy

Conversation

@matanlurey

Copy link
Copy Markdown
Contributor

Three unrelated documentation-accuracy fixes bundled together per maintainer instruction, since none of them require code behavior changes.

#452: README described retroglyph-widgets' old free-function architecture

The Widgets section (and the crate table's one-line description) said every widget is a free function (panel, gauge, table, sparkline, draw_box, ...). That's stale: every widget is a builder struct (Panel, Gauge, Table, Sparkline, BoxBorder, List, Tabs, Button, Scrollbar, ProgressBar, Modal, StatBar, Meter, Log) that draws itself via Widget/StatefulWidget, matching crates/widgets/src/lib.rs's own doc comment and crates/widgets/README.md. Rewrote both README sections to describe the current shape. crates/widgets/AGENTS.md was already accurate and needed no change.

#451: README advertised Style text modifiers and Terminal::modifier() that don't exist

The Grid API and Stateful drawing API sections claimed cells carry text modifiers (bold/italic/underline/...) and that modifier() is a method alongside fg()/bg(). Style (crates/core/src/style.rs) has only fg/bg fields; no modifier field or method exists anywhere in the workspace. Removed both false claims and added a short explanation of the no-modifier-by-design rationale, pointing at Style's own doc comment for the full reasoning. No code change: per the issue, deleting the false claims is the resolution regardless of the separate text-attributes design question.

#466: docs.rs showed no feature badges, gated items looked unconditionally available

Every crate already set all-features = true under [package.metadata.docs.rs] but none set rustdoc-args, so docs.rs never enabled cfg-based feature badges. Added to all 8 publishable crates:

[package.metadata.docs.rs]
all-features = true
rustdoc-args = ["--cfg", "docsrs"]

and to each crate's lib.rs:

#![cfg_attr(docsrs, feature(doc_cfg))]

Deviation from the issue's literal snippet: the issue asked for feature(doc_auto_cfg))], but on current nightly that feature has been removed and merged into doc_cfg (rustc note: "removed in 1.92.0 ... merged into doc_cfg", see rust-lang/rust#138907). doc_cfg now auto-infers cfg badges from #[cfg(feature = ...)] the same way doc_auto_cfg used to, so this uses the current feature name to keep the badge generation working against the nightly docs.rs builds against today, rather than shipping something that would silently stop compiling on their pinned toolchain.

Also added just doc-docsrs (RUSTDOCFLAGS="--cfg docsrs" cargo +nightly doc --all-features --no-deps --open) matching the issue's requested verification recipe.

Verification

  • just doc-docsrs run locally on nightly-aarch64-apple-darwin (rustc 1.98.0-nightly): full workspace builds clean under --cfg docsrs.
  • Confirmed the "Available on crate feature X only" badge renders on the generated HTML for all five items called out in the issue:
    • retroglyph_core::layout (module) -- egc
    • retroglyph_core::grid::BlendMode -- gem
    • retroglyph_core::app::run_blocking -- std
    • retroglyph_software::tileset (module) -- tilesets
    • retroglyph_widgets::widget::Paragraph -- egc
  • cargo check --workspace --all-features on stable: clean, confirming cfg_attr(docsrs, ...) is a no-op off nightly.
  • just check (fmt-check, clippy -D warnings incl. pedantic/nursery, compile, 878 tests, doc): all green.

Fixes #452
Fixes #451
Fixes #466

@matanlurey matanlurey self-assigned this Jul 26, 2026
@github-actions github-actions Bot added c:workspace Workspace-wide: tooling, CI, root docs, release config c:core crates/core c:terminal crates/terminal c:crossterm crates/crossterm c:terminal-wasm crates/terminal-wasm c:software crates/software c:window crates/window c:widgets crates/widgets c:gl crates/gl labels Jul 26, 2026
@matanlurey
matanlurey enabled auto-merge (squash) July 26, 2026 01:14
… feature badges

- README's Widgets section and crate table described retroglyph-widgets'
  old free-function architecture (panel/gauge/table/sparkline/draw_box);
  rewrite to describe the current builder-struct widgets.
- README claimed Style has text modifiers and a modifier() method; neither
  exists. Remove the claims and point at Style's own no-modifier rationale.
- Add rustdoc-args = ["--cfg", "docsrs"] to every publishable crate's
  [package.metadata.docs.rs], plus #![cfg_attr(docsrs, feature(doc_cfg))]
  to every crate's lib.rs, so docs.rs renders feature-gate badges instead
  of showing gated items as unconditionally available. doc_auto_cfg was
  merged into doc_cfg upstream, so doc_cfg (which now auto-infers cfg
  badges) is used instead of the now-removed doc_auto_cfg feature name.
  Adds a just doc-docsrs recipe to verify the docs.rs build locally.
@matanlurey
matanlurey force-pushed the docs/readme-accuracy branch from 3d4ac2f to 11547a5 Compare July 26, 2026 01:52
@matanlurey
matanlurey merged commit c279a47 into main Jul 26, 2026
27 checks passed
@matanlurey
matanlurey deleted the docs/readme-accuracy branch July 26, 2026 01:55
@github-actions github-actions Bot mentioned this pull request Jul 26, 2026
matanlurey added a commit that referenced this pull request Jul 28, 2026
…cy (#586)

retroglyph-window's doctests build a real SoftwareRenderer (the only real
Presenter impl available) for run_windowed_with_proxy/
run_windowed_with_typed_proxy, so window carries a dev-only dependency back
on retroglyph-software -- its own dependent. Cargo explicitly supports this
shape (a dev-dependency pointing back at a crate's dependent isn't part of
that crate's real build graph), so it's fine on its own.

The dev-dependency entry also pinned version = "0.5.0", though, and that's
where cargo publish's packaging step differs from cargo build: packaging
generates a full Cargo.lock for the extracted package, which resolves every
dependency section -- dev included -- against the registry, not just what a
plain build needs. release-plz#417 bumped both window (0.3.1 -> 0.4.0) and
software (0.4.0 -> 0.5.0) in the same release for the first time since this
dev-dependency was added in #499, so window's manifest pointed at software's
not-yet-published 0.5.0 while software's manifest (a real, regular
dependency) pointed at window's not-yet-published 0.4.0. Neither could
publish first:

  https://github.com/crates-lurey-io/retroglyph/actions/runs/30325033949/job/90168521377

  error: failed to prepare local package for uploading
  Caused by:
    failed to select a version for the requirement `retroglyph-software = "^0.5.0"`
    candidate versions found which didn't match: 0.4.0, 0.3.1, 0.3.0, ...

A path dev-dependency with no version key is dropped from the published
manifest entirely instead of being resolved against the registry (Cargo
reference, "Multiple locations"), which breaks the cycle. Local
builds/doctests are unaffected -- path resolution inside the workspace never
consulted the version key to begin with.

Verified with cargo package -p retroglyph-window --allow-dirty (full verify
build, no --no-verify): packages and builds cleanly without ever resolving
retroglyph-software. cargo test -p retroglyph-window --doc still compiles
the affected doctests via the workspace path. just check passes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

c:core crates/core c:crossterm crates/crossterm c:gl crates/gl c:software crates/software c:terminal crates/terminal c:terminal-wasm crates/terminal-wasm c:widgets crates/widgets c:window crates/window c:workspace Workspace-wide: tooling, CI, root docs, release config

Projects

None yet

1 participant