gdnative-doc

This is a documentation tool for godot-rust projects.

WARNING: very unstable at the moment.

The goal of this tool is to automate writing documentation in Rust code that will be used in gdscript.

Features

Keep the documentation synchronized with your code.
Generate readable and easy to change markdown
Build table of contents automatically.
Automatic linking to the godot documentation.
Generate gut tests from gdscript examples.

Example

An example: process function

Input: Rust

/// Process the given [`String`], returning [`FAILED`] on error.
///
/// # Example
/// ```gdscript
/// var processor = Myprocessor.new()
/// assert_eq(processor.process("hello"), OK)
/// ```
#[export]
pub fn process(&mut self, _: &Node, s: GodotString) -> i32 { /* ... */ }

Output: Markdown

### <a id="func-process"></a>func process(s: [String]) -> [int]

Process the given [`String`], returning [`FAILED`] on error.

#### Example
```gdscript
var processor = Myprocessor.new()
assert_eq(processor.process("hello"), OK)
```

[String]: https://docs.godotengine.org/en/stable/classes/class_string.html
[`String`]: https://docs.godotengine.org/en/stable/classes/class_string.html
[int]: https://docs.godotengine.org/en/stable/classes/class_int.html
[`FAILED`]: https://docs.godotengine.org/en/stable/classes/class_@globalscope.html#enum-globalscope-error

Output: Gut

func test_process():
    var processor = Myprocessor.new()
    assert_eq(processor.process("hello"), OK)

A more complete example can be found in the examples/dijkstra-map-gd directory.

Usage

This is meant to be used as a build script: Set

[build-dependencies]
gdnative-doc = "*"

In your Cargo.toml. Then you can drive the process with the Builder structure:

// in build.rs
use gdnative_doc::{backend::BuiltinBackend, init_logger, Builder, LevelFilter};
use std::path::PathBuf;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    init_logger(LevelFilter::Info)?;
    Builder::new()
        .add_backend(BuiltinBackend::Markdown, PathBuf::from("doc/markdown"))
        .build()?;
    Ok(())
}

More informations can be found in the documentation.

The format of the configuration file can be found here.

You can also use the command-line tool.

Limitations

At the moment, syn is used to parse rust and search for the struct and impls. This is not optimal however and might sometime mess up link resolution. rust-analyzer libraries will probably be used in the future to avoid this.

License

astrale-sharp/gdnative-doc-rs

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages