rhai-doc - 从Rhai脚本文件生成HTML文档

rhai-doc是一个用于自动生成Rhai脚本文档的工具。

它支持在Rhai脚本的文档注释中编写Markdown文档，并创建通用文档页面。

示例请参见这里。

命令行界面

USAGE:
    rhai-doc.exe [OPTIONS] [SUBCOMMAND]

OPTIONS:
    -a, --all              Generate documentation for all functions, including private ones
    -c, --config <FILE>    Set the configuration file [default: rhai.toml]
    -d, --dir <DIR>        Set the Rhai scripts (*.rhai) directory [default: .]
    -D, --dest <DIR>       Set the destination for the documentation output [default: dist]
    -h, --help             Print help information
    -p, --pages <DIR>      Set the directory where MarkDown (*.md) pages files are located [default:
                           pages]
    -v, --verbose          Use multiple to set the level of verbosity: 1 = silent, 2 (default) =
                           full, 3 = debug
    -V, --version          Print version information

SUBCOMMANDS:
    help    Print this message or the help of the given subcommand(s)
    new     Generates a new configuration file

安装

从crates.io安装

cargo install rhai-doc

从源代码安装

cargo install --path .

配置文件

要开始，你需要一个配置文件。

通常命名为rhai.toml，或者你可以通过--config选项指定。

要生成一个rhai.toml骨架，使用new命令

rhai-doc new

示例

version = "1.0"                         # version of this TOML file
name = "My Rhai Project"                # project name
color = [246, 119, 2]                   # theme color
root = "/docs/"                         # root URL for generated site
index = "home.md"                       # this file becomes 'index.html`
icon = "logo.svg"                       # project icon
stylesheet = "my_stylesheet.css"        # custom stylesheet
code_theme = "atom-one-light"           # 'highlight.js' theme
code_lang = "ts"                        # default language for code blocks
extension = "rhai"                      # script extension
google_analytics = "G-ABCDEF1234"       # Google Analytics ID

[[links]]                               # external link for 'Blog'
name = "Blog"
link = "https://example.com/blog"

[[links]]                               # external link for 'Tools'
name = "Tools"
link = "https://example.com/tools"

配置选项

• version：此TOML文件的版本；1.0是当前版本。
• name：项目的名称（如果有的话）。它是文档页面显示的标题。
• color：生成的文档主题颜色的RGB值（如果有的话）。
• root：文档中生成的根URL（如果有的话）。
• index：主Markdown文件（如果有的话），将成为index.html。
• icon：自定义图标文件的路径（如果有的话）。
• stylesheet：自定义样式的路径（如果有的话）。
• code_theme：代码块中的语法高亮主题（默认 default），由 highlight.js 提供。
• code_lang：代码块的默认语言（默认 ts）。
• extension：脚本文件 rhai-doc 将查找的扩展名（默认 .rhai）。
• google_analytics：如果有，提供 Google Analytics ID。
• [[links]]：如果有，提供其他相关网站的外部链接。
  • name：外部链接的标题。
  • link：外部链接的 URL。

/// This function calculates a **secret number**!
///
/// Formula provided from this [link](https://secret_formula.com/calc_secret_number).
///
/// # Scale Factor
/// Uses a scale factor obtained by calling [`get_contribution_factor`].
///
/// # Parameters
/// `seed` - random seed to start the calculation
///
/// # Returns
/// The secret number!
///
/// # Exceptions
/// Throws when the seed is not positive.
///
/// # Example
/// ```
/// let secret = calc_secret_number(42);
/// ```
fn calc_secret_number(seed) {
    if seed <= 0 {
        throw "the seed must be positive!";
    }

    let factor = get_contribution_factor(seed);

    // Some very complex code skipped ...
    // ...
}

/// This function is private and will not be included
/// unless the `-a` flag is used.
private fn get_multiply_factor() {
    42
}

/// This function calculates a scale factor for use
/// in the [`calc_secret_number`] function.
fn get_contribution_factor(x) {
    x * get_multiply_factor()
}