Repository navigation
fix(workspace): correct README architecture/style claims, add docs.rs feature badges - #499
Merged
Merged
Conversation
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
force-pushed
the
docs/readme-accuracy
branch
from
July 26, 2026 01:52
3d4ac2f to
11547a5
Compare
Merged
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.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
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 architectureThe 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 viaWidget/StatefulWidget, matchingcrates/widgets/src/lib.rs's own doc comment andcrates/widgets/README.md. Rewrote both README sections to describe the current shape.crates/widgets/AGENTS.mdwas already accurate and needed no change.#451: README advertised
Styletext modifiers andTerminal::modifier()that don't existThe Grid API and Stateful drawing API sections claimed cells carry text modifiers (bold/italic/underline/...) and that
modifier()is a method alongsidefg()/bg().Style(crates/core/src/style.rs) has onlyfg/bgfields; nomodifierfield or method exists anywhere in the workspace. Removed both false claims and added a short explanation of the no-modifier-by-design rationale, pointing atStyle'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 = trueunder[package.metadata.docs.rs]but none setrustdoc-args, so docs.rs never enabled cfg-based feature badges. Added to all 8 publishable crates: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 intodoc_cfg(rustc note: "removed in 1.92.0 ... merged intodoc_cfg", see rust-lang/rust#138907).doc_cfgnow auto-infers cfg badges from#[cfg(feature = ...)]the same waydoc_auto_cfgused 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-docsrsrun locally onnightly-aarch64-apple-darwin(rustc 1.98.0-nightly): full workspace builds clean under--cfg docsrs.Xonly" badge renders on the generated HTML for all five items called out in the issue:retroglyph_core::layout(module) --egcretroglyph_core::grid::BlendMode--gemretroglyph_core::app::run_blocking--stdretroglyph_software::tileset(module) --tilesetsretroglyph_widgets::widget::Paragraph--egccargo check --workspace --all-featureson stable: clean, confirmingcfg_attr(docsrs, ...)is a no-op off nightly.just check(fmt-check, clippy-D warningsincl. pedantic/nursery, compile, 878 tests, doc): all green.Fixes #452
Fixes #451
Fixes #466