Aquamarine

编译器支持：此 crate 需要 rustc 1.38.0 或更高版本

Aquamarine 是 rustdoc 的过程宏扩展，旨在通过使用 mermaid.js 图表来改善 Rust 文档的视觉组件。

#[aquamarine] 宏通过将 mermaid.js 嵌入生成的 rustdoc HTML 页面，修改文档注释属性来实现。

要将图表内联到文档中，请使用 doc-string 中的 mermaid 碎片。

#[cfg_attr(doc, aquamarine::aquamarine)]
/// ```mermaid
/// graph LR
///     s([Source]) --> a[[aquamarine]]
///     r[[rustdoc]] --> f([Docs w/ Mermaid!])
///     subgraph rustc[Rust Compiler]
///     a -. inject mermaid.js .-> r
///     end
/// ```
pub fn example() {}

图表将替换 mermaid 代码块，并保留其周围的注释。您甚至可以添加多个图表！

要查看演示，请访问 demo crate 的 docs.rs 页面。

有关 mermaid.js 及其功能的更多信息，请参阅 mermaid 的 文档 MdBook。

暗黑模式

Aquamarine 将自动选择默认的 dark 主题，如果当前的 rustdoc 主题是 ayu 或 dark。

在更改主题后，您可能需要重新加载页面以重新绘制图表。

自定义主题

支持在图表级别进行主题化，通过 mermaid 的 %%init%% 属性。

注意：自定义主题将覆盖默认主题

/// ```mermaid
/// %%{init: {
///     'theme': 'base',
///     'themeVariables': {
///            'primaryColor': '#ffcccc', 
///            'edgeLabelBackground':'#ccccff', 
///            'tertiaryColor': '#fff0f0' }}}%%
/// graph TD
///      A(Diagram needs to be drawn) --> B{Does it have 'init' annotation?}
///      B -->|No| C(Apply default theme)
///      B -->|Yes| D(Apply customized theme)
/// ```

有关更多信息，请参阅 mermaid.js 书籍的 主题化部分。

将图表与代码分离

可以通过从文件中加载图表或多个图表来减少文档注释中的混乱。

#[cfg_attr(doc, aquamarine::aquamarine)]
/// My diagram #1
/// include_mmd!("diagram1.mmd")
/// My diagram #2
/// include_mmd!("diagram2.mmd")
pub fn example_foad_from_file() {}

在野外

在文档中使用 aquamarine 的存储箱

• google/autocxx
• replicadse/senile
• teloxide

以及其他