DocFx & Unity with GitLab CI/CD

I recently set up one of my Unity projects to use DocFx this was an interesting endeavour, getting DocFx to work offline was relatively easy with a few modifications to the normal templates. Getting it running on GitLab CI/CD was somewhat trickier.

Local Setup

After following the tutorials to install DocFx we go to our Unity project folder and call docfx init -q this creates a docfx_project folder with some default settings, now we can start editing some settings in docfx.json.

We need to add the Unity project files, so it knows where everything is. We change the source to up a level in the folder, and tell it to use all *.csproj files it finds.

"metadata": [
    {
      "src": [
        {
          "src": "../",
          "files": [
            "**.csproj"
          ]
        }
      ],
      "dest": "api",
      "globalNamespaceId": "Global",
      "filter": "filterconfig.yml"
    }

Don’t miss the extra metadata, "globalNamespaceId": "Global", this allows the Global namespace to be detected by DocFx. We also defined a filterconfig.yml this is set up based on the default-filter-configuration. But I did add some extra exclusions, like below, so it doesn’t end up with a massive inherited member list, though this is just my preference.

apiRules:
- exclude:
    uidRegex: ^System
- exclude:
    uidRegex: ^UnityEngine

It can also be handy to add unwanted third party Api’s assuming they haven’t been changed.

- exclude:
    uidRegex: ^DigitalRubyShared

We could also try and use a cross reference to hook into Unity’s Documentation to link up the two when it builds.

Now we can start the server and should have our site running on our localhost. docfx build --serve

GitLab CI/CD & GitLab Pages

Using the *.csproj for building the docs requires syncing the *.csproj with our git repository but Unity auto-generates these and does not guarantee they will be in the same format each time and files could be changed without updating the *.csproj (using VSCode for example) and it is generally advised that these aren’t committed to your git repository.

Luckily the DocFx docs also state it’s not required when generating metadata directly from source code (.cs, .vb) or assemblies (.dll). This means we can changes over to just using the original files, although we do lose information from within UnityEngine & UnityEditor namespaces etc. but we were going to lose that anyway unless we planned on pushing all the Unity.dll's to git (don’t do that).

To change over to just using the *.cs files we change where it searches for our source files in the docfx.json.

"src": [
  {
    "src": "../Assets",
    "files": [
      "**.cs"
    ]
  }
],

This has the added advantage of making the GitLab CI/CD a bit easier as it doesn’t require msbuild and all its dependencies, allowing us to use a linux based docker image.

I’ve set up a docker image that uses mono and DocFx to allow us to build on GitLab.

As GitLab pages only support static pages we have to make sure it stays a static site, we set this within the "build": section in our docfx.json.

"template": [
  "statictoc"
],

The gitlab-ci.yml is quite basic, it just runs docfx, and moves it to our public artifacts place for pages.

pages:
  image: erothejoker/docker-docfx:latest
  script:
    - docfx docfx_project/docfx.json
    - mv docfx_project/_site public
  artifacts:
    paths:
      - public
  only:
    - master

It’s worth noting this must be run as a pages: step for it to actually publish to your GitLab pages, this is also limited to only working on the master branch.

Next Steps

Now we have DocFx working with GitLab pages to generate documentation, we want to flesh out the docfx_project/articles and other markdown files for our site. My next steps are trying to setup an external reference for Unity classes so it links into the Unity Scripting Documentation.

I also want to dig into into templates more, I currently use them to hide the Assembly: cs.temp.dll.dll in class files that is there because we generate from source files so don’t know any assembly info.