rhai-autodocs

从 rhai::Engine 实例生成 Markdown/MDX 文档。

使用 Mdbook 发布。 使用 Docusaurus 发布。

功能

• 将本机 Rust Rhai 函数和自定义类型文档导出到简单的结构体中。
• 为 Mdbook 和 Docusaurus 分别生成带有 HTML 或 MDX 的文档。
• 使用 # rhai-autodocs:index:x 指令对文档中的函数进行排序。
• 使用文档中的 # 字符将文档分成 '部分'，这些部分将被渲染为标签页。
• 生成与函数定义链接的术语表。

如何使用

use rhai::exported_module;
use rhai::plugin::*;

// 1. Create a plugin module or any kind of Rhai API that supports documentation on functions and types.

/// My own module.
#[export_module]
mod my_module {
    use rhai::plugin::*;

    /// A function that prints to stdout.
    ///
    /// # Args
    ///
    /// * message - append a message to the greeting. (optional)
    ///
    /// # rhai-autodocs:index:1
    #[rhai_fn(global, name = "hello_world")]
    pub fn hello_world_message(message: &str) {
        println!("Hello, World! {message}");
    }

    // NOTE: since this function is an overload of "hello_world", the documentation can
    //       be written once on one of the functions, no need to write it multiple times.
    #[rhai_fn(global, name = "hello_world")]
    pub fn hello_world() {
        println!("Hello, World!");
    }

    /// A function that adds two integers together.
    ///
    /// # rhai-autodocs:index:2
    #[rhai_fn(global)]
    pub fn add(a: rhai::INT, b: rhai::INT) -> rhai::INT {
        a + b
    }

    /// Documentation for functions that do not have the index preprocessor
    /// is ignored.
    #[rhai_fn(global)]
    pub fn dont_care() {
        println!("nope");
    }
}

// 2. Generate the docs with autodocs. This library can be imported as a
//    build dependency into your build script.
//    A typical documentation generation workflow would look like this:

// Specify an environment variable that points to the directory
// where the documentation will be generated.
let docs_path = std::env::var("DOCS_DIR").unwrap_or("target/docs".to_string());

// Create a new engine and register all modules that need to have documentation generated
// for them. In this example, the module defined in the previous code block is registered
// into the engine, but you could register other functions and types ...
let mut engine = rhai::Engine::new();
engine.register_static_module("my_module", exported_module!(my_module).into());

/// Export the documentation as a [`ModuleDocumentation`]. You could stop here and generate
/// you own docs from this structure.
let docs = rhai_autodocs::export::options()
    .include_standard_packages(false)
    .export(&engine)
    .expect("failed to export documentation");

/// Or you could use pre-defined templates for docusaurus or mdbook.
/// Here, documentation is generated for docusaurus with some options.
let mdx = rhai_autodocs::generate::docusaurus()
    .with_slug("/docs/api")
    .generate(&docs)
    .expect("failed to generate mdx for docusaurus");

/// Iterate over the generated documentation for every modules.
for (name, docs) in mdx {
    // Write the documentation in a file, or output to stdout, or anything really.
    println!("docs for module {name}");
    println!("{docs}");
}

有关更多详细信息，请查看 示例 文件夹。

生成自己的文档

您可以使用任何模板系统来生成文档。但是，这个存储库已经根据 handlebars 使用 handlebars-rust crate 为 docusaurus 和 mdbook 生成文档。您可以通过查看 模板文件夹 来获得灵感。