How to build an automated API website for your Unity project or package Part 1

I'd like to share my journey on how I build the Stan's Assets API website for our Unity plugins and packages. I am really happy with it, hope you guys will like it too. Or maybe this article will help you to build something similar.

This is awesome how may great open source and free products are available for fellow developers. I would like to share how we built an automated API Reference website for our Unity products using DocFx + GitHub Pages + GitHub Actions that is fully automated and costs $0 to maintain and support!

How it works

• The DocFix is used to generate static websites from the C# source code.
• Generated website is hosted with GitHub Pages
• Every time we commit something to our products master branch that is touching C# the website will be regenerated and re-deployed.

If you are interested I will explain how that was made step by step below. Let's start with a quick walkthrough of the free/open-source products I used.

DocFx

• Getting Started Guide
• Themes

Other nice looking static websites powered by DocFx

• Testify Git repo | Website

Github pages
The static site will be hoster from the master branch / master branch docs folder / gh-pages branch (whatever you prefer in your repository settings.)

Subdomain set up
You can also set up a custom domain for your Github website. The stansassets.com is registered on GoDaddy so I only had to make few simple steps:

• In repository Options - set a custom subdomain to api.stansassets.com
• Add domain CNAME record: api / stansassets.github.io

Few related tutorials

• How to Use a GoDaddy Custom Subdomain with GitHub Pages Hosting
• Using custom domain for GitHub pages
• Does GitHub Pages Support HTTPS for www and @ subdomains?

GitHub Actions
GitHub Actions is a CD /CI tools that kick off workflows with GitHub events like push, issue creation, or a new release. You can read more about it here

The Setup
Now let's finally talk about setting things up.

DocFx Setup
First, you need to configuration docfx.json to set up your website menu, and show do DocFX where is the source code located you would like to generate documentation for. You can also set up ignore rules etc. I was incredibly surprised when it just worked with the basic set up. But to be completely honest I did spend a few days reading manuals and going though examples before I was able to shape it up to the point where I 100% happy with that.

Theme.
Since I am making Unity related products I wasn't the website to look similar to well known and loved Unity API Reference and to my luck, the DocFx already provided a UnityFX template that looks super similar. You can also check out other available templates as well as make your own. The template setup was incredibly simple as well. All I had to do is:

• clone template repo and place it under templates/unity folder.
• updated docfx.json with "template": ["default", "templates/unity"]

I was pretty much happy with the way theme looks out of the box, but probably made few minor changes to my liking. That is also very straight forward since all the theme files are open source.

Documentation chapter home
The next thing I wanted is for each chapter to have the home page. Where I can explain a little bit about the products while having a documentation table of content on aside. That took a while, and DocFx still throws some warnings about my solutions, but hey... it works and I haven't found a better way to do it. My solution was to update tol.yml as follows:

Code (CSharp):

1. - name: Foundation Lib
2.   href: foundation
3. - name: Ultimate Mobile
4.   href: ultimate-mobile
5. - name: iOS Native
6.   href: ios-native
7. - name: Android Native
8.   href: android-native

Not the foundation/ - that's important, even those DocFx complains. And place index.md file to a correspondent folder, for example: docfx-project/foundation/index.md

Website Icon
That was the easiest thing to figure out To replace the website favicon.ico I just placed one into the docfx project folder root docfx-project/favicon.ico And to set the header icon I placed the one I want to use into images/logo_rect_blue.png and updated template nav bar to use it docfx-project/templates/unity/partials/navbar.tmpl.partial

Code (CSharp):

1. <img id="logo" src="{{_rel}}images/logo_rect_blue.png" height="46" width="46" alt="{{_appName}}" >

GitHub Actions setup
Of course, I do not want to update this website by hand all the time. I would like the CD / CI magic to do that for me. But let's talk about that in another article, since this one is big enough already.

Also as you probably saw already, but the repository for api.stansassets.com is open, so feel free to check it out. Thanks!