These instructions describe how to set up DocFX and publish documentation as a static website to your repository's GitHub Pages. They are targeted at Hollow Knight modders and use some conventions that have been generally adopted in the Hollow Knight modding community, but should be generally applicable to other types of projects as well.
As a note before we begin, much of this content has room for preferential variation. In general, this documentation assumes the following:
- You have an existing C# project that you want to add docs to (i.e. you are not starting from scratch) and that your project is in the the default C# project layout (solution in its own folder, csproj's nested one level deeper alongside their contents).
- You want your documentation in a folder named
docsinside the top-level solution directory, and will document only one project in your solution. - You want your documentation to be hosted on a separate git branch, named
docs-source.
If you want to deviate from this pattern, that is certainly acceptable, but the copy-paste-ability of some of the resources I will share here will be reduced. I will point out some of the places you may want to make changes and the side-effects of those changes when applicable.
This step is not strictly necessary, but will provide more tools to easily initialize your documentation setup and allow you to preview your changes locally before pushing them.
There are several ways to install and use DocFX. In my experience, DocFX's tooling is generally overly opinionated, and as such I strongly recommend using DocFX as a command-line tool installed through a package manager (Chocolatey on Windows or Homebrew on OSX/Linux). This is simply because the CLI does the least for you, and therefore gives you the most control over how you want to structure your project. DocFX's documentation tells you how to do this with links to the package managers as well if you don't have them installed.
Before you start, you should stash or commit any current changes you have in development so you won't lose them if anything goes wrong.
- Open a terminal in the directory with your solution in it (or wherever else you may want your docs to reside).
- Run
docfx init. This wizard will present you with several configuration options. In my experience, the defaults are all fine, but review them all in case you want to make changes. mv docfx_project docs- Open docs/docfx.json in your favorite text editor. We'll want to make some changes.
- In the src section of the metadata section, add a
srcproperty pointing to.., like so. This allows docfx to start searching for source files up a level rather than from within the docs folder. If you have multiple projects in the solution, you should also change the files section from**/**.csprojtoYourProjectName/**.csprojso you don't generate extra documentation. - Optionally, in the build section, link to the .NET xref service so that DocFX can link to documentation for framework types, like so.
- Optionally, create a filter config to ignore certain namespaces/types/whatever, like so. The format of the filter config file is well-documented here.
- In the src section of the metadata section, add a
- Run
docfx docs/docfx.json --serveto make sure your docs will build and preview them in a browser. - Gitignore the docs directory you've created from your main branch; commit that before continuing.
cd docs- Initialize the docfx project as its own git root:
git init - Create and checkout a branch for docs:
git checkout -b docs-source - Add your git repo as a remote:
git remote add origin <your github repo link>.git - Set the upstream branch:
git branch -u origin/docs-source - Commit and push your changes to docs.
If you want your docs on your main branch, you can simply skip steps 6-11.
Now that your docs are set up and hosted, you'll want to automate their build and publish process. Still in your docs folder on the
docs-source branch, create a folder .github/workflows. In that folder, you'll create a workflow definition. You should more-or-less
be able to copy-paste this file.
Any changes you've made to branch/folder naming and file placement will need to be reflected here as well. Committing and pushing this
will run the workflow, and publish your website to a new branch gh-pages. Then, in your repository settings under "Code and
Automation," go to Pages, and select the gh-pages branch to publish, and use the root directory.
Once you've verified your actions are working, you'll need a copy of your workflow on your main branch as well. As-is, your site will only be updated when changes are made to docs-source because Github assumes that nobody uses orphan branches. The benefit of this is that you can also set different triggers on main (e.g. you might want to update your API docs only when a new release is published, but update your articles any time you push changes on docs-source).