Doc generation: msg variants as enum-parity children, contract polish, theming hooks#1419
Open
micahscopes wants to merge 7 commits intoargotorg:masterfrom
Open
Doc generation: msg variants as enum-parity children, contract polish, theming hooks#1419micahscopes wants to merge 7 commits intoargotorg:masterfrom
micahscopes wants to merge 7 commits intoargotorg:masterfrom
Conversation
Previously `msg` blocks' desugared Mod + per-variant structs leaked into docs: variants emitted as top-level DocItems with struct-shaped pages, URLs used /mod and /struct suffixes, and the module nav tree double- listed each variant. This produced broken links (/struct and /mod 404s), duplicated items, and pages that treated message variants as if they were structs rather than variant subsections of their parent msg. Changes: - extract.rs: detect desugared msg Mods and synthesized variant structs/ impls via HirOrigin markers. Skip them from module item lists and populate the parent msg DocItem's `children` array with variant-shaped entries (kind: "variant", matching enum variants). Narrows msg variant field signatures to "field: Type" rather than the whole variant body. - symbol.rs: `item_kind_to_url_suffix` returns "msg" for desugared msg Mods and "msg_variant" for variant structs instead of the generic "mod" and "struct". `scope_to_doc_path` rewrites msg_variant paths to `<parent>/msg~variant.<name>` anchors so clicks land on the parent msg page rather than a non-existent variant page. Also used by LSP goto/hover and SCIP symbol doc_url generation. - scip_index.rs: `overlay_occurrences` prefers the more-specific symbol when two non-definition occurrences share a byte range, so variant names inside a msg block link to the variant rather than the parent namespace. Child doc_url generation collapses to the parent anchor when that anchor already contains `~` (viewer extracts the first tilde as the anchor, so nested anchors wouldn't route). - fe-doc-item.js / fe-doc-viewer.js / fe-web.js / fe-search.js: add msg and msg_variant to the kind maps used for URL suffix resolution, display metadata, and search. Most were working by fallback accident; explicit entries keep the four files in sync.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: d8d9cb94c0
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
Schema goes from v2 to v4: v3 drops standalone msg_variant items in favor of variant-kind children of their parent msg; v4 adds explicit init/recv_handler children for contract pages.
The fe-doc-nav had `overflow-y: auto` which per CSS spec promotes `overflow-x` from `visible` to `auto`, producing an awkward horizontal scrollbar whenever sidebar entries (long test function names, etc.) exceeded the sidebar width. Default browser scrollbars also read as light-mode chrome on the dark theme. - `.fe-doc-nav`: explicit `overflow-x: hidden`, dedicated webkit scrollbar styling using `--border` thumb and `--bg-secondary` track. - `.fe-nav-items a`: `overflow-wrap: anywhere` + `word-break: break-word` so long underscored symbols wrap within the sidebar. - Global body: `scrollbar-width: thin` + `scrollbar-color` for Firefox, `::-webkit-scrollbar*` rules for Chromium/WebKit using theme vars.
Adds first-class doc rendering for contract bodies and a handful of UX
fixes surfaced during review.
- Contract pages now emit `init` and `recv_handler` children alongside
fields. `extract.rs` walks the init block and each `recv <Msg> { … }`
arm, emitting a DocChild per entry. New DocChildKind::Init /
RecvHandler, wired into fe-doc-item / fe-web CHILD_KIND maps with
plurals "Initializer" and "Message Handlers".
- Schema bump to v4 (additive -- contracts gain children). fe-scip-store
migration just updates version number; consumers of v3 data regen.
- `fe doc` hides `#[test]`-annotated items by default; new
`--include-tests` flag restores them. Bountiful sidebar drops from
~800 items to ~80.
- Ingot root modules no longer display as `lib`; extractor substitutes
the ingot's configured name (games, registry, shared, etc.).
- Deep links with `~anchor` suffixes now reliably scroll to the target:
fe-doc-viewer retries anchor resolution for up to 1s while content
renders; member-items carry inline scroll-margin-top so rows aren't
hidden under sticky headers.
- Variant and handler rows are wrapped in anchor links so clicks
anywhere in the row hit the row's anchor (previously only the `§`
glyph was clickable).
- Search results with null doc_url (SCIP-only matches from builtin
stdlib) are filtered out rather than rendering as broken `href="#"`
links.
- SCIP signature-link overlay excludes byte ranges inside `#[…]`
attributes, which were being wrongly attributed to random stdlib
symbols (most visibly, every `#[selector = sol(...)]` attribute on
msg variants pointed at Encode::encode_to_ptr).
Exposes CSS custom properties at :root so downstream consumers can
retheme the doc viewer by overriding a handful of variables rather
than waging specificity battles.
Knobs added:
- Fonts: --fe-body-font, --fe-heading-font, --fe-mono-font
- Weights: --fe-body-weight, --fe-heading-weight,
--fe-sidebar-weight, --fe-current-weight
- Pixel-rendering: --fe-font-smoothing, --fe-moz-font-smoothing,
--fe-text-rendering, --fe-letter-spacing,
--fe-heading-text-shadow, --fe-emphasis-text-shadow
- Layout: --fe-content-max-width, --fe-sidebar-min-width,
--fe-sidebar-max-width
All hardcoded "JetBrains Mono" / "Fira Code" strings replaced with
var(--fe-mono-font); body and headings now consume the weight and
rendering vars. The `h1..h6` block centralizes heading styling so
themes only set variables instead of per-element selectors.
Sidebar behavior adjusted to accommodate variable-width content:
grid-template-columns switches from fixed `280px 1fr` to `auto 1fr`,
with sidebar width driven by `width: max-content` between the new
sidebar min/max vars. Long names no longer wrap; horizontal scroll
on the sidebar itself is the fallback for outliers.
Responsive (max-width: 768px) block resets the sidebar's min/max
back to a fixed 280px so mobile layout is unchanged.
micahscopes
force-pushed
the
msg-doc-overhaul
branch
from
d8d9cb9 to
4d3fc24
Compare
Collaborator
Author
|
Pushed fixes for both Codex P2 findings:
Squashed into the relevant commits ( |
micahscopes
force-pushed
the
msg-doc-overhaul
branch
from
4d3fc24 to
f5e390d
Compare
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
1 participant
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.
Summary
Restructures
msgrendering so variants live as variant-kind children of the parent msg page (mirrors enum variants), adds first-classinitandrecv_handlerchildren for contract pages, and parameterizes the doc viewer for downstream theming. Also fixes the doc-site deploy ref.Changes
msgvariants asvariantchildren of their parent msg; drop the standalone msg_variant DocItemInitandRecvHandlerDocChildKinds for contract pagesSCHEMA_VERSION2 → 4; add v2→v3 and v3→v4 migrations infeMigrate/modlibon the root module pagefe doc --include-tests; default off (test fns pollute the public API sidebar)doc_url(they rendered as unclickable links)gh-pages→main(matches the actual fe-docs branch GitHub Pages serves from)Notes
Existing 26.0.0 / 26.0.1 doc bundles will run the v2→v3 migration in-browser and lose msg-variant rows. Worth a follow-up regeneration pass for prior versions once this lands.
Test plan
cargo test -p fe-web— schema snapshot consistencyfe docagainst a contract with msgs — variants render under their parent msg pagefe docagainst a contract withinit/ receive handler — both surface as contract page children