Skip to content

Latest commit

 

History

History
352 lines (272 loc) · 7.67 KB

README.md

File metadata and controls

352 lines (272 loc) · 7.67 KB
Raw

Unreal Doc

Tool for generating documentation from Unreal C++ sources.

Table of contents

  1. About
  2. Installation
  3. Config file
    1. Simple config setup for baking into JSON portable format
    2. Simple config setup for baking into MD Book
    3. Advanced config setup for baking into MD Book
  4. Markdown doc comments
  5. Markdown book pages
  6. Run documentation baking command
  7. Examples

About

Do you create an Unreal Engine plugin and need to generate a documentation combined with book for it, but Doxygen seems limited or sometimes not working at all?

Fear not - this tool understands Unreal C++ header files syntax and Markdown doc comments, it can also bake a book pages out of Markdown files, all of that being able to cross-reference each other!

Installation

Config file

Config TOML file tells this tool evenrythig about how to build documentation for your project. At this moment there are two baking backends available:

  • Json

    Portable representation of documentation and book that can be used in third party applications with custom way of baking documentation.

  • MdBook

    Uses MD Book for baking HTML5 bundle for online or offline web books.

Although config file can be named whatever you want, it's a good rule to give config file UnrealDoc.toml name.

Simple config setup for baking into JSON portable format

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

  • input_dirs

    List of directories and Unreal C++ header or Markdown files this tool should read.

  • output_dir

    Path to directory where generated documentation should be put.

Simple config setup for baking into MD Book

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

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

  • backend

    Specifies MD Book baking backend.

  • backend_mdbook.title

    Title of the generated documentation and book bundle.

  • backend_mdbook.build

    Set to true if this tool should also run mdbook build command on generated files to build HTML5 version of the bundle, ready to put online.

  • backend_mdbook.cleanup

    Set to true if this tool should cleanup output_dir directory before baking new files. Useful for ensuring no old/unwanted files will exist between iterations of documentation baking.

Advanced config setup for baking into 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.header

    Path to file that contains Markdown content that will be put on every documentation and book page header section.

  • backend_mdbook.footer

    Path to file that contains Markdown content that will be put on every documentation and book page footer section.

  • backend_mdbook.assets

    Path to directory that contains assets (usually images/animations/videos) referenced in documentation and book pages.

Markdown doc comments

Overview of all possible things you can do with Markdown doc comments.

#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 book pages

Standard expected structure of the book Markdown files:

  • documentation.md (optional)

    This is essentially the content of main page of your documentation + book, a hello page you can call it. it has to be placed in root of book source Markdown files directory.

  • index.txt (required)

    This file contains a list of files or directories with optional names (useful mostly for directories). The order specified in this file will match order on side pages index.

    some_book_page.md
directory_with_subpages: Title on side pages index

  • index.md (optional)

    Markdown file content used in to describe content of given directory content. First line of the content will be used as title of the directory on side pages index.

    # Book

Optional directory content description

  • hello.md

    Content for given book page. First line will be used as page title on side pages index.

      # Hello World!

  Lorem ipsum dolor amet

  ```cpp
  void main() {
      printf("Hello World!");
  }
  ```

Run documentation baking command

Once you have config file and documentation itself all in place, it's time to actually bake documentation and book bundle:

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

Example

If you want to see an example of decoumentation and book source files structure, take a look at /resources directory in this repository or more real life example that can be found here: https://github.com/PsichiX/Unreal-Systems-Architecture/tree/master/Plugins/Systems/Documentation

Real life example of baked plugin documentation: https://psichix.github.io/Unreal-Systems-Architecture/systems