Unreal Doc
Tool for generating documentation from Unreal C++ sources.
Table of contents
- About
- Installation
- Config file
- Markdown doc comments
- Markdown book pages
- Run documentation baking command
- 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
- Installation using
cargo-install
from Rust toolset: - Pre-built binaries
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
= ["./source"]
= "./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
= ["./source"]
= "./docs"
= "MdBook"
[]
= "Documentation"
= true
= 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
= ["./source"]
= "./docs"
= "MdBook"
[]
= true
= true
= true
[]
= "Documentation"
= true
= true
= "header.md"
= "footer.md"
= "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.
using Foo = std::vector<int>;
;
;
;
void* ;
/// Description of enum
///
/// More information and examples.
enum class Something : uint8
;
/// Description of struct
///
/// More information and examples.
///
/// [`struct: Self::Foo`]()
/// [`struct: Self::A`]()
;
/// Description of class
///
/// More information and examples.
///
/// [`class: Self::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
/// ```
void*
//// [snippet: wait_what]
;
//// [/snippet]
/// Proxy documentation for injecting code with macros.
///
//// [proxy: injectable]
//// void Injected() const;
//// [/proxy]
;
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.
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:
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