How to Automate Documentation Generation

I don’t know about most, but I sure find it very painful to write documentation for all of my code. I always wondered if there was some tool that will do it for me. Apparently, there are indeed tools that does make your life a lot easier. Some are good for specific technology stacks. For me, I needed to write a documentation for a unity library. So, I ended up using something called docfx.

Apparently, there’s a version of it that works for unity as well. This article is about how to setup your development pipeline in a way that you can utilize this tool.

Just so you know this is a bare minimum workflow for docfx so that we can utilize it without much of a headache. However, this library is very rich. It is a one stop solution for generating documentation.

Code Level Setup

It’s not exactly a setup. What you need to do is like follow standards and the tool will generate the documentation for you.

• Proper Encapsulation: The library would by default only generate documentation for public methods. Of course, we can configure it. But as I said before we want to get the most out of it without any configuration
• XML Comment: In Visual Studio if you just type /// on top of any class, method, property you should see a template xml comment. Fill it out so that the documentation generation tool can use this to add human readable details on top of its default generation. More details can be found here Example XML documentation comments — C# | Microsoft Learn

Project Level Setup

While just code level setup is enough. However, it would only generate the Scripting API. It won’t have any details on how to use or changelogs or license information. We would want those too.

• LICENCE: We just need to keep our LICENCE file at the root of the project before generating our documentation.
• Changelog: As your code changes you would want to maintain a changelog. So, we need to keep a changelog document at the root of the project as well before generation. There’s not exactly any defined standard for this but you can follow this Keep a Changelog.
• README: This is your base user manual. It should contain information regarding how to use the library. This should also be at the root of the project.

GitHub Setup

Once everything is ready, you would want to automate the documentation generation. This can be done via GitHub Actions.

for my setup I’ve used this for the workflow generation

name: docfx-unitypackageon:
  workflow_dispatch:
  push:
    branches:
      - main
jobs:
  build-and-deploy:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v3
        with:
          submodules: true
      
      - name: Find and copy specific files
        run: |
            # Look for LICENSE.md, README.md, and CHANGELOG.md in subdirectories
            find . -name LICENSE.md -exec cp {} . \;
            find . -name README.md -exec cp {} . \;
            find . -name CHANGELOG.md -exec cp {} . \;
            # Check if a "Screenshots" folder exists and copy it to the root
            if [ -d "Screenshots" ]; then
              cp -r Screenshots .
            fi
        shell: bash
      
      - name: Build
        uses: CaseyHofland/docfx-unitypackage@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
      - name: Deploy
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_branch: gh-pages
          publish_dir: _site

In my case I didn’t have the License, Readme or changelog at the root, so I told the action to find and copy those to the root before building the document. I used a GitHub action called docfx-unitypackage.

It does the heavy lifting for us. Once it’s done, we would want to host it somewhere. Since GitHub offers free site hosting, we can just host the files there. and for this we push all the generated html files to gh-pages branch. After that we can just go to settings > pages and select source as Deploy from branch and select gh-pages and from root.

After a while you should be able to see your documentation hosted on GitHub.

It should look something like this SaveSystem | | (studio-23-xyz.github.io)

Of course, you can host it on your own site or other providers such as Vercel.