22 releases (4 breaking)
new 0.5.4 | Apr 26, 2024 |
---|---|
0.4.3 | Feb 5, 2024 |
0.4.1 | Nov 1, 2023 |
0.1.7 | May 3, 2023 |
0.1.6 | Mar 23, 2023 |
#217 in Development tools
914 downloads per month
Used in 3 crates
51KB
1K
SLoC
rhai-autodocs
Generate Markdown/MDX documentation from a rhai::Engine
instance.
Published with Mdbook. Published with Docusaurus.
Features
- Output native Rust Rhai function and custom types documentation as Markdown with HTML and Docusaurus with MDX.
- Function ordering using the
# rhai-autodocs:index:x
directive in your docs. - Rust docs 'sections' (
# Section
in markdown) displayed with tabs.
How to use
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}");
}
/// 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() {
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());
let mut engine = rhai::Engine::new();
// We register the module defined in the previous code block for this example,
// but you could register other functions and types ...
engine.register_static_module("my_module", exported_module!(my_module).into());
let docs = rhai_autodocs::options()
.include_standard_packages(false)
.generate(&engine)
.expect("failed to generate documentation");
// Write the documentation in a file, or output to stdout, etc.
for (name, docs) in rhai_autodocs::generate_for_docusaurus(&docs).expect("failed to generate mdx for docusaurus") {
println!("docs for module {name}");
println!("{docs}");
}
You need to import the styles/default.css
file and src/tabs.js
script for everything to work correctly using the mdbook generation. (You can of course override the styles and javascript code if you wish)
For more details, see the examples.
Dependencies
~7.5MB
~144K SLoC