Skip to content

Latest commit

 

History

History
215 lines (158 loc) · 6.72 KB

README.md

File metadata and controls

215 lines (158 loc) · 6.72 KB
Raw

rhai-doc - Generates HTML Documentation from Rhai Script Files

License crates.io crates.io

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.

CLI Interface

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

Installation

Install from crates.io

cargo install rhai-doc

Install from source

cargo install --path .

Configuration File

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:

rhai-doc new

Example

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"

Configuration options

  • version: Version of this TOML file; 1.0 is the current version.
  • 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.
  • code_theme: The highlight.js theme for syntax highlighting in code blocks (default default).
  • code_lang: Default language for code blocks (default ts).
  • 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.

Doc-Comments

Rhai supports doc-comments in MarkDown format on script-defined functions.

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

Syntax Highlighting

highlight.js is used for syntax highlighting in code blocks.

The default language for code blocks is ts (i.e. TypeScript). This default is chosen because Rhai syntax mostly resembles JavaScript/TypeScript, and highlighting works properly for strings interpolation.

Inter-Script Links

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).

MarkDown Pages

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.

Features

  • Generate documentation from MarkDown doc-comments in Rhai script files.
  • Create general-purpose documentation pages.
  • Text search.
  • Linter for undocumented functions, parameters, etc.

License

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.