Crate doc_item

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.