Building documentation

DocFX is a static site generator (like Jekyll or Hugo) that can also generate API documentation of .NET projects. PleOps Cake provides tasks to build documentation projects with DocFx.

If you don't have one project already, follow their quick guide or take our template project.

The template project also provides some adjustments over the default modern template. Check them out if you are interested. For instance, you can put your GitHub icon in the main.js file.

The build system expects to find a docfx.json file in docs/. If you create the project in other folder, adjust the build context in BuildLifetime.Setup():

context.DocFxContext.DocFxFile = "Documentation/DocFX/docfx.json";

You see the output by running:

dotnet docfx docs/docfx.json --serve

Note

If you open the build output in your browser directly (index.html), the site will look like broken. The generated site requires an HTTP server to see properly. You can use the one from DocFX: dotnet docfx serve build/artifacts/docs

Changelog

If you check the Bundle task we created, you will see we run first the task ExportReleaseNotesTask. This task generates two files from the release information in GitHub:

• CHANGELOG.md: it contains the release notes of every released version.
• CHANGELOG.NEXT.md: it contains the release notes of GitHub release that matches the current build version. This will only works when building from a git tag that matches the GitHub release.
  • This file is included in the NuGet packages in the property PackageReleaseNotes.

The name of these files can be configured through build context. At build time, DocFX will take the CHANGELOG.md file and copy it into the documentation project. You can adjust this behavior and path with the build context of DocFx (ChangelogDocPath).

Note

If you don't use GitHub releases or prefer to write manually the release notes, you can not add the task ExportReleaseNotesTask. The documentation and NuGet pack will still look for those files in your repo.