Setting up DocFX for a Unity project

This document describes how you setup DocFX for a typical game project. For general info about DocFX, consult the online documentation.

Installation

• Download the latest release from the DocFX Github repository.
• Unzip it to a suitable folder (as example: C:\docfx ).
• Set up the path environment variable to include this directory.

Now you're all set.

Setup

• Open a shell (windows-r => "cmd") and change to the folder of your unity project. This is the folder that contains the Assets-folder for the Unity project!
• The command for initializing docfx is

docfx init -q

• This creates a folder docfx_project in the project directory and adds the default project files.
• Open the file docfx.json in a text editor. This is the basic settings file for the docfx processor.
• Change the metadata => src tag like this:

"metadata":
[
    {
    "src":[
        {
            // scc can also point directly to the game folder, 
            // then you won't need the exclude settings.
            "src":"../Assets",
            "files": [
                // "**.csproj",            
                // "**.sln"
                "**.cs"
            ],
            "exclude": [
                "**/Plugins/**",
                "**/Editor/**"
                ],
        },
    ],
    "dest": "api",
    "disableGitFeatures": false,
    "disableDefaultFilter": false
    }
]

• If you want to include external HTML-files, you need to setup build=>resource like this:

"resource": [
    {
        "files": [
            "images/**",
            // The next line will include 
            // html files in the articles folder
            "articles/**.html"
        ]
    }
],

• Set the build=>dest tag to something easier, i usually set it up like this:

"dest": "../docu",

• Very important! Make sure you add the statictoc template, if you want it to work also locally.

"template": [
    "default", "statictoc" 
],

• If you want to add a custom icon and title for your documentation, change the build=>globalMetadata to something like this (Make sure there is an icon file at that location!):

"globalMetadata":
{
    "_appLogoPath" : "images/DungeonKeeper.png",
    "_appTitle": "Dungeon Keeper Project"
},

These settings are of course just a recommendation, you're free to change everything according to your own taste, but do so on your own risk. Consult the online documentation for further information.

Building the documentation

To build the documentation, simply start DocFX in the docfx_project folder. DocFX will find all necessary files on its own and generate all documentation files in the directory set in the docfx.jsjon file.

To browse the documentation, simply open index.html in the destination folder in any modern browser.

Editing the table of content

The TOC is defined in the YAML-file "toc.yml" in the docfx_project folder. It's pretty self-explaining.

Editing articles

Articles are a list of Markdown-files, which can be created and edited by any text editor. A more comfortable way is using a specialized Markdown editor like Typora.

Further remarks

Docfx also supports a live view option via this commando:

docfx build docfx.json --serve

After the start it is accessable at http://localhost:8080