doc_item

项目级文档定制属性。

此软件包提供属性，以便在通过 rustdoc 进行文档时向项目添加各种功能。这包括定义项目信息文档框、注释项目的最低版本以及标记项目在模块列表中显示为半透明。

这允许增强文档，类似于标准库中通过 staged_api 功能和夜间版中的 doc_cfg 功能所做的那样。然而，此软件包提供了更多的定制，允许使用自定义 CSS 类和文档框内的文本。

使用方法

定义实验性 API

将项目标记为实验性（类似于通过标准库中的 #[unstable] 属性所做的那样）可以按照以下方式完成

/// 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() {}

创建自定义样式的文档框

您可以创建自己的自定义样式来自定义文档框的显示。按照以下方式定义您的项目文档框

/// 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() {}

然后，在单独的 HTML 文件中创建一个样式定义。

<style>
    .custom {
        background: #c4ffd7;
        border-color: #7bdba1;
    }
</style>

最后，将 HTML 文件的全部内容包含到您的文档中

$ RUSTDOCFLAGS="--html-in-header custom.html" cargo doc --no-deps --open

并指示 docs.rs 也包含该 HTML 文件的内容，通过向您的 Cargo.toml 添加

[package.metadata.docs.rs]
rustdoc-args = [ "--html-in-header", "custom.html" ]

示例

在 /examples 目录中提供了几个示例。生成的示例文档可在此查看 这里。

如果您想自己运行这些示例，请运行以下命令

cargo rustdoc --example <example>

其中 <example> 是您想要运行的示例名称。如果示例需要自定义样式，请按照以下方式包含相关的HTML文件：

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

最低支持的Rust版本

本库保证在 rustc 1.58.0 及更高版本上正常工作。它可能在更早的版本上编译，但不能保证所有功能都能正常显示。

夜间稳定性

由于 docs.rs 在 nightly 频道上构建文档，因此本库将尝试在 nightly 上保持功能。由于本库的功能依赖于将HTML注入到生成的文档中，而HTML的内部布局可能会更改，因此 nightly 的功能可能会偶尔中断。请在GitHub仓库中报告您发现的问题。

许可协议

本项目采用以下任一许可协议：

• Apache License，版本 2.0 (LICENSE-APACHE 或 https://apache.ac.cn/licenses/LICENSE-2.0)
• MIT许可协议 (LICENSE-MIT 或 http://opensource.org/licenses/MIT)

任您选择。

贡献

除非您明确声明，否则根据Apache-2.0许可协议定义的，您有意提交以包含在本作品中的任何贡献，都将如上所述双重许可，没有附加条款或条件。