rhai-doc - Generates HTML documentation from Rhai script files
rhai-doc is a tool for auto-generating documentation for [Rhai] scripts.
It supports writing [MarkDown] documentation in [doc-comments] of [Rhai] scripts and creating general-purpose documentation pages.
See an example here.
```text USAGE: rhai-doc [FLAGS] [OPTIONS] [SUBCOMMAND]
FLAGS: -h, --help Prints help information -V, --version Prints version information -v Use multiple to set the level of verbosity: 1 = silent, 2,3 (default) = full
OPTIONS:
-c, --config
SUBCOMMANDS: help Prints this message or the help of the given subcommand(s) new Generates a new 'rhai.toml' configuration file ```
crates.iosh
cargo install rhai-doc
sh
cargo install --path .
To get started, you need a configuration file.
It is usually named rhai.toml, or you can specify one via the -config option.
To generate a skeleton rhai.toml, use the new command:
sh
rhai-doc new
``toml
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 = "mystylesheet.css" # custom stylesheet
extension = "rhai" # script extension
googleanalytics = "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" ```
name: The name of the project, if any. It's the title that shows up on the documentation pages.color: RGB values of the theme color for the generated docs, if any.root: The root URL generated as part of the documentation, if any.index: The main [MarkDown] file, if any, that will become index.html.icon: The location of a custom icon file, if any.stylesheet: The location of a custom stylesheet, if any.extension: The extension of the script files rhai-doc will look for (default .rhai).google_analytics: Google Analytics ID, if any.[[links]]: External links, if any, to other sites of relevance.
name: Title of external link.link: URL of external link.[Rhai] supports [doc-comments] in [MarkDown] format on script-defined functions.
rust
/// 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 = calcsecretnumber(42);
/// ```
fn calcsecretnumber(seed) {
if seed <= 0 {
throw "the seed must be positive!";
}
let factor = get_contribution_factor(seed);
// Some very complex code skipped ...
// ...
}
/// This function calculates a scale factor for use
/// in the [calc_secret_number] function.
fn getcontributionfactor(x) {
x * 42
}
```
Functions documentation can cross-link to each other within the same script file.
A link in the format [`my_func`] is automatically expanded to link to the documentation of
the target function (in this case my_func).
By default, rhai-doc will generate documentation pages from [MarkDown] documents within a
pages sub-directory under the scripts directory.
Alternatively, you can specify another location via the --pages option.
Licensed under either of the following, at your choice:
Unless explicitly stated otherwise, any contribution intentionally submitted for inclusion in this crate, as defined in the Apache-2.0 license, shall be dual-licensed as above, without any additional terms or conditions.