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" ]

Examples

Several examples are provided in the /examples directory. The documentation generated by the examples is viewable here.

If you would like to run the examples yourself, run the following command:

cargo rustdoc --example <example>

where <example> is the name of the example you would like to run. If the example requires custom styling, include the relevant HTML file as follows:

cargo rustdoc --example <example> -- --html-in-header examples/<example>.html

Minimum Supported Rust Version

This crate is guaranteed to function properly on rustc 1.58.0 and up. It may compile on earlier versions, but it is not guaranteed that all features will display properly.

Nightly Stability

As docs.rs builds documentation on the nightly channel, this crate will attempt to maintain functionality on nightly. As this crate's functionality relies on injecting HTML into the generated documentation, and internal layout of HTML is subject to change, nightly functionality may occasionally break. Please report issues as you find them on the associated github repository.

License

This project is licensed under either of

• Apache License, Version 2.0 (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.