diff options
Diffstat (limited to 'docs-rs')
| -rw-r--r-- | docs-rs/README.md | 17 | ||||
| -rw-r--r-- | docs-rs/trait-tags.html | 177 |
2 files changed, 194 insertions, 0 deletions
diff --git a/docs-rs/README.md b/docs-rs/README.md new file mode 100644 index 00000000..3be1087a --- /dev/null +++ b/docs-rs/README.md @@ -0,0 +1,17 @@ +## Docs.rs Extensions + +This directory includes some templates and styling to extend and modify [rustdoc]'s output +for Azalea's documentation on [docs.rs]. + +See [Bevy's documentation](https://github.com/bevyengine/bevy/tree/main/docs-rs) for more info. + +## Local Testing + +Build the documentation with the extension enabled like this: + +```bash +RUSTDOCFLAGS="--html-after-content docs-rs/trait-tags.html --cfg docsrs_dep" RUSTFLAGS="--cfg docsrs_dep" cargo doc --no-deps --package <package_name> +``` + +[rustdoc]: https://doc.rust-lang.org/rustdoc/what-is-rustdoc.html +[docs.rs]: https://docs.rs diff --git a/docs-rs/trait-tags.html b/docs-rs/trait-tags.html new file mode 100644 index 00000000..e34614ee --- /dev/null +++ b/docs-rs/trait-tags.html @@ -0,0 +1,177 @@ +<script> + // Adds tags to documentation pages for common Bevy traits like `Component` or `Resource`. + // This makes it easier to see at a glance what types are used for. + // + // This extension is passed to `rustdoc` using the `--html-after-content` flag. + + // Traits that we want to show as tags. + // Order determines sort order of items in listings. + const bevyTraits = [ + 'Plugin', + 'PluginGroup', + 'Component', + 'Resource', + 'Asset', + 'Event', + 'Message', + 'ScheduleLabel', + 'SystemSet', + 'SystemParam', + 'Relationship', + 'RelationshipTarget' + ]; + + // Find all traits that are implemented by the current type. + const implementedBevyTraits = findImplementedBevyTraits(document); + + // If we found any implemented traits, add them as tags to the top of the page. + if (implementedBevyTraits.size > 0) { + // Create a container for the tags. + const heading = document.body.querySelector(".main-heading h1"); + const tagContainer = document.createElement('div'); + tagContainer.className = 'bevy-tag-container'; + heading.appendChild(tagContainer); + + // Check if an implemented trait has a `type Mutability = Immutable` associated type. + // This is used to determine if a `Component` is immutable or not. + // TODO: Ideally we should just check the associated types of the `Component` trait, + // but the docs.rs layout makes it tricky to do so in a robust way. + const associatedTypeHeader = document.querySelectorAll(".trait-impl.associatedtype .code-header"); + const isImmutable = [...associatedTypeHeader].some(el => el.innerText.includes('type Mutability = Immutable')); + + // Create a tag for each implemented trait. + for (let [tagName, href] of implementedBevyTraits) { + if (tagName == 'Component' & isImmutable) { + tagName = 'Immutable Component'; + } + + // Create the tag and append it to the container. + tagContainer.appendChild(createBevyTag(tagName, href)); + } + } + + function findImplementedBevyTraits(doc) { + // Traits that are implemented by the current type. + // The key is the trait name, and the value is the href to the trait's documentation. + const implementedTraits = new Map(); + + // Find all trait implementation headers. + const allTraitHeaders = doc.body.querySelectorAll( + '#trait-implementations-list .impl .code-header, #blanket-implementations-list .impl .code-header' + ); + + for (const header of allTraitHeaders) { + // We can extract the trait name by removing any generics and splitting the string by spaces. + // This results in ['impl', 'TraitName', 'for', 'TypeName']. + const traitName = removeGenerics(header.innerText).split(' ')[1].trim(); + + // Find the link to the trait if the anchor element exists. + // Otherwise, the trait is just in plain text. + const traitLinkEl = [...header.children].find(el => el.getAttribute('href')?.includes(`trait.${traitName}.html`)); + const href = traitLinkEl?.getAttribute('href'); + + implementedTraits.set(traitName, href); + } + + const implementedBevyTraits = new Map( + [...implementedTraits].filter(([traitName, _]) => bevyTraits.find((x) => x == traitName)) + ); + + return implementedBevyTraits; + } + + // Helper function to remove generics from a string of Rust code. + // For example, 'Vec<T>' would become 'Vec'. + function removeGenerics(str) { + // Remove the innermost generics. + const newStr = str.replace(/<([^<>])*>/g, ''); + + // If there are still generics, perform the removal again recursively. + if (newStr !== str) { + return removeGenerics(newStr); + } + + // No more generics to remove. + return newStr; + } + + // Helper function to create a tag element with the given name and href, + // if available. + function createBevyTag(tagName, href) { + const el = document.createElement('a'); + const kebabCaseName = tagName.toLowerCase().replace(' ', '-'); + + if (href) { + el.setAttribute('href', href); + } + + el.innerText = tagName; + el.className = `bevy-tag ${kebabCaseName}-tag`; + return el; + } +</script> + +<style> + .bevy-tag-container { + padding: 0.5rem 0; + display: flex; + flex-wrap: wrap; + gap: 0.5rem; + } + + .bevy-tag { + display: flex; + align-items: center; + width: fit-content; + height: 1.5rem; + padding: 0 0.5rem; + border-radius: 0.75rem; + font-size: 1rem; + font-weight: normal; + color: white; + } + + .bevy-tag { + background-color: var(--tag-color); + } + + .component-tag, + .immutable-component-tag { + --tag-color: oklch(50% 27% 80); + } + + .resource-tag { + --tag-color: oklch(50% 27% 110); + } + + .asset-tag { + --tag-color: oklch(50% 27% 0); + } + + .event-tag { + --tag-color: oklch(50% 27% 310); + } + + .message-tag { + --tag-color: oklch(50% 27% 190); + } + + .plugin-tag, + .plugingroup-tag { + --tag-color: oklch(50% 27% 50); + } + + .schedulelabel-tag, + .systemset-tag { + --tag-color: oklch(50% 27% 270); + } + + .systemparam-tag { + --tag-color: oklch(50% 27% 240); + } + + .relationship-tag, + .relationshiptarget-tag { + --tag-color: oklch(50% 27% 150); + } +</style>
\ No newline at end of file |