Unreal Doc

从 Unreal C++ 源代码生成文档的工具。

目录

1. 关于
2. 安装
3. 配置文件
   1. 将配置设置成 JSON 可移植格式
   2. 将配置设置成 MD Book
   3. 高级配置设置成 MD Book
4. Markdown 文档注释
5. Markdown 书籍页面
6. 运行文档烘焙命令
7. 示例

关于

你创建了一个 Unreal Engine 插件并需要为其生成文档和书籍，但 Doxygen 似乎有限制或有时根本无法工作？

无需担心 - 这个工具理解 Unreal C++ 头文件语法和 Markdown 文档注释，它还可以从 Markdown 文件中烘焙书籍页面，所有这些都可以相互交叉引用！

安装

• 使用 cargo-install 从 Rust 工具集 安装

  cargo install unreal-doc
  

• 预构建的二进制文件

配置文件

配置 TOML 文件告诉这个工具如何为你的项目构建文档。目前有两个烘焙后端可用

• Json

  文档和书籍的便携式表示，可用于第三方应用程序，以自定义的方式烘焙文档。

• MdBook

  使用 MD Book 为在线或离线网页书籍烘焙 HTML5 套件。

虽然配置文件可以命名为任何你想要的名字，但将配置文件命名为 UnrealDoc.toml 是一个好习惯。

将配置设置成 JSON 可移植格式

input_dirs = ["./source"]
output_dir = "./docs"

• input_dirs

  该工具应读取的目录列表和 Unreal C++ 头文件或 Markdown 文件。

• output_dir

  生成的文档应放置的目录的路径。

将配置设置成 MD Book

input_dirs = ["./source"]
output_dir = "./docs"
backend = "MdBook"

[backend_mdbook]
title = "Documentation"
build = true
cleanup = true

• backend

  指定 MD Book 烘焙后端。

• backend_mdbook.title

  生成的文档和书籍包的标题。

• backend_mdbook.build

  如果此工具还应在生成的文件上运行 mdbook build 命令以构建 HTML5 版本的包，请设置为 true，以便将其上线。

• backend_mdbook.cleanup

  如果此工具应在烘焙新文件之前清理 output_dir 目录，请设置为 true。这对于确保在文档烘焙迭代之间不会存在旧的/不需要的文件非常有用。

高级配置设置成 MD Book

input_dirs = ["./source"]
output_dir = "./docs"
backend = "MdBook"

[settings]
document_private = true
document_protected = true
show_all = true

[backend_mdbook]
title = "Documentation"
build = true
cleanup = true
header = "header.md"
footer = "footer.md"
assets = "assets/"

• backend_mdbook.标题

  包含将放置在每个文档和书籍页面标题部分的Markdown内容的文件的路径。

• backend_mdbook.页脚

  包含将放置在每个文档和书籍页面页脚部分的Markdown内容的文件的路径。

• backend_mdbook.资产

  包含在文档和书籍页面中引用的资产（通常是图像/动画/视频）的目录路径。

Markdown 文档注释

Markdown文档注释可以执行的所有可能操作的概述。

#pragma once

using Foo = std::vector<int>;

enum class Something : uint8;

template <typename T>
struct BAR Foo : public Bar;

class FOO Bar;

template <typename T>
void* Main(const Foo& Arg);

/// Description of enum
///
/// More information and examples.
UENUM(BlueprintType, Meta = (Foo = Bar))
enum class Something : uint8
{
	A,
	B
};

/// Description of struct
///
/// More information and examples.
///
/// [`struct: Self::Foo`]()
/// [`struct: Self::A`]()
USTRUCT(BlueprintType, Meta = (Foo = Bar))
template <typename T>
struct BAR Foo : public Bar
{
protected:
	/// What is this method
	///
	/// What it does
	UFUNCTION()
	virtual void Foo(
		/// Argument
		int A,
		/// Argument with default value
		AActor* B = nullptr) const override;

private:
	/// What is this property
	///
	/// What impact does it have
	UPROPERTY()
	int A[] = {0};
};

/// Description of class
///
/// More information and examples.
///
/// [`class: Self::Bar`]()
UCLASS()
class FOO Bar
{
public:
	/// What is this method
	///
	/// What it does
	Bar();
};

/// What is this function
///
/// What does it do
///
/// [`function: Self`]()
///
/// See:
/// - [`enum: Something`]()
/// - [`struct: Foo`]()
/// - [`struct: Foo::Foo`]()
/// - [`struct: Foo::A`]()
/// - [`class: Bar`]()
/// - [`function: Main`]()
///
/// # Examples
/// ```snippet
/// hello_world
/// ```
/// ```snippet
/// hello_world2
/// ```
/// ```snippet
/// wait_what
/// ```
template <typename T>
void* Main(
	/// Some referenced data
	const Foo& Arg)
{
	//// [snippet: hello_world]
	if (true)
	{
		printf("Hello");
	}
	//// [/snippet]

	//// [snippet: hello_world2]
	printf("World");
	//// [/snippet]
}

//// [snippet: wait_what]
struct Wait
{
	int What = 0;
};
//// [/snippet]

/// Proxy documentation for injecting code with macros.
///
//// [proxy: injectable]
//// void Injected() const;
//// [/proxy]
#define INJECT            \
	void Injected() const \
	{                     \
	}

struct Who
{
	int What = 0;

	void SetWhat(int InWhat)
	{
		//// [ignore]
		this->What = InWhat;
		//// [/ignore]
	}

    /// Operator overload.
	friend bool operator==(const Who& Lhs, const Who& Rhs)
	{
		//// [ignore]
		return Lhs.What == Rhs.What;
		//// [/ignore]
	}

	//// [inject: injectable]
	INJECT
};

Markdown 书籍页面

书籍Markdown文件的预期标准结构

• documentation.md（可选）

  这是文档和书籍主页的内容，你可以称之为问候页。它必须放在书籍源Markdown文件目录的根目录中。

• index.txt（必需）

  此文件包含具有可选名称的文件或目录列表（主要用于目录）。此文件中指定的顺序将匹配侧页索引中的顺序。

  some_book_page.md
  directory_with_subpages: Title on side pages index
  

• index.md（可选）

  Markdown文件内容用于描述给定目录的内容。内容的第一行将被用作侧页索引中目录的标题。

  # Book
  
  Optional directory content description
  

• hello.md

  给定书籍页面的内容。第一行将被用作侧页索引中页面的标题。

    # Hello World!
  
    Lorem ipsum dolor amet
  
    ```cpp
    void main() {
        printf("Hello World!");
    }
    ```
  

运行文档烘焙命令

一旦配置文件和文档本身都准备就绪，就可以实际制作文档和书籍包了。

unreal-doc -i path/to/UnrealDoc.toml

示例

如果您想查看解耦文档和书籍源文件结构的示例，请查看此存储库中的 /resources 目录或更多真实示例，可以在以下位置找到：https://github.com/PsichiX/Unreal-Systems-Architecture/tree/master/Plugins/Systems/Documentation

实际烘焙插件文档的示例：https://psichix.github.io/Unreal-Systems-Architecture/systems