Repository navigation
feat(ladfile): readable generated binding docs in mdbook - #679
Merged
Merged
Conversation
One page per type with its functions as sections (signature, docs, arguments), grouped into functions, methods, operators and variant functions. Fixes generics rendered as HTML tags, escaped and flattened previews, unresolved rustdoc links, doc headings outranking the page, unknown type ids leaking into titles and links, and multi-line docs breaking tables. Adds lad.css for the generated pages.
… book - `()` had an empty title and a `.html` page no link reached - mermaid-init.js looked up the mdbook 0.4 theme button ids and threw on every page - multi-code-block.js used the highlight.js 10.7 API, mdbook bundles 10.1, so lua/rune examples failed to highlight - rust examples from Rust docs are `noplayground`, they need crates the playground doesn't have
… types like primitives mdbook nests the sidebar by section numbers, so generated chapters are numbered again and lad.css hides the numbers. Types standing for primitives are named like them (`f32`, not `F32`), also in titles, and the types of a namespace are sorted in the sidebar like in its table.
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.
Reworks how
mdbook_lad_preprocessorrenders the generated binding docs. Reviewed against the full book (cargo xtask docs, all binding features) with screenshots before/after, and clicked through in headless Chromium.Bugs fixed
Type<A>,Optional<A>,Handle<ScriptAsset>.asset_pathrendered asType,Optional,Handle.asset_path(the 11 mdbook warnings).# Example,Returns: *squashed into one line). Now the first paragraph, cut after a sentence or at a word, with formatting kept (docstrings::summary). The oldmarkdown_substringsliced by byte and is removed.[`Transform`],[text](bevy_math::Vec3),[x][ref]+ reference definitions resolve to type pages, or become plain text (was literal brackets / deadhref="bevy_ecs::…").# Exampleswas an<h1>mid-page); rustdoc-hidden# use …example lines are dropped; the///leading space is removed; rust examples arenoplayground(they need crates the playground doesn't have).Unknownwithout a link (wasArc<TypeId(0x…)>linking to a missing page), also in titles.()gets a title and aunitpage (was an empty title and.html).mermaid-init.jslooked up the mdbook 0.4 theme button ids (nowmdbook-theme-*), andmulti-code-block.jsused the highlight.js 10.7 API while mdbook bundles 10.1, so lua/rune example tabs weren't highlighted.Structure / look and feel
### name {#anchor}), not pages of their own. Book pages 2165 → 332; the sidebar lists a type's functions under it. Generated chapters are unnumbered (no more19.1.29.0.37.).get_component<A>(entity: Entity, registration: Type<A>) -> Optional<A>, plus "Generic overA, the type given asregistration".Handle.new).f32,bool),HashSet<T>printed (was justT), variadics as....17 types, 3 functions).docs/lad.css(scoped to generated pages via a.lad-pagemarker): full-width left-aligned tables with a light header, signature block, dividers between function sections, badges; content width 750 → 900px.No LAD format changes.
Checked
#anchors).looking_at→transform.html#looking_at.mdbook_lad_preprocessorunit tests (newdocstringstests), book integration snapshot blessed,cargo test -p ladfile_builder -p ladfile -p lua_language_server_lad_backend -p mdbook_lad_preprocessor.