gdnative-doc

这是一个用于 godot-rust 项目的文档工具。

警告：目前非常不稳定。

此工具的目的是自动化Rust代码中用于gdscript的文档的编写。

功能

• 保持文档与您的代码同步。
• 生成可读且易于更改的Markdown。
• 自动生成目录。
• 自动链接到 godot文档。
• 从gdscript示例生成 gut 测试。

示例

示例： process 函数

• 输入：Rust

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

• 输出：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/[email protected]#enum-globalscope-error
  

• 输出：Gut

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

更完整的示例可以在 examples/dijkstra-map-gd 目录中找到。

用法

这应该用作 构建脚本：设置

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

在您的Cargo.toml中。然后您可以使用 Builder 结构来驱动此过程

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

更多信息请参阅 文档。

配置文件格式可以在 此处 找到。

您还可以使用 命令行工具。

Godot版本

支持的Godot版本有 3.2，3.3，3.4 和 3.5。默认情况下，将选择 3.5。要选择其他版本，请使用配置文件的 godot_version 字段。

限制

目前使用syn来解析Rust代码并搜索struct和impl。然而，这种方法并非最佳，有时可能会搞砸链接解析。未来可能会使用rust-analyzer库来避免这种情况。