Crate doc_item[−][src]
Attributes for item-level documentation customization.
This crate provides attributes for adding various features to items when they are documented by
rustdoc
. This includes defining
item-info docboxes, annotating an item’s minimum version, and marking an item to be displayed as
semi-transparent on module lists.
This allows for enhanced documentation, similar to what is done in the standard library with the
staged_api
feature and what is available on nightly with the
doc_cfg
feature.
However, this crate provides even more customization, allowing for use of custom CSS classes and
text within docboxes.
Usage
Defining an Experimental API
Marking an item as experimental (similar to what is done in the standard library through the
#[unstable]
attribute) can be
done as follows:
/// This is an experimental API. /// /// The docbox will indicate the function is experimental. It will also appear semi-transparent on /// module lists. #[doc_item::docbox(content="<span class='emoji'>🔬</span> This is an experimental API.", class="unstable")] #[doc_item::short_docbox(content="Experimental", class="unstable")] #[doc_item::semi_transparent] pub fn foo() {}
Creating Custom-Styled Docboxes
You can create your own custom styles to customize the display of docboxes. Define your item’s docbox as follows:
/// An item with a custom docbox. /// /// The docbox will be a different color. #[doc_item::docbox(content="A custom docbox", class="custom")] #[doc_item::short_docbox(content="Custom", class="custom")] pub fn foo() {}
Next, create a style definition in a separate HTML file.
<style>
.custom {
background: #c4ffd7;
border-color: #7bdba1;
}
</style>
Finally, include the HTML file’s contents in your documentation:
$ RUSTDOCFLAGS="--html-in-header custom.html" cargo doc --no-deps --open
And instruct docs.rs to include the HTML file’s contents as well by adding to your Cargo.toml
:
[package.metadata.docs.rs]
rustdoc-args = [ "--html-in-header", "custom.html" ]
Attribute Macros
docbox | Adds a docbox to the item’s item-info. |
semi_transparent | Makes an item semi-transparent in module lists. |
short_docbox | Adds a short docbox to the item in module lists. |
since | Adds a minimal version to an item. |