README.md

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.