Creating Correct Source Code Links with DocFX in Jenkins

Georg Dangl by Georg Dangl in Continuous Integration Sunday, November 12, 2017

Sunday, November 12, 2017

Posted in Jenkins

If you haven't used it yet, you should check out DocFX to automate your documentation generation. It's working great with .Net Core projects, is simple to use and easily customizable. It's also got a feature to link directly from your documentation to source code on GitHub, but this comes with a small catch: When running the build in Jenkins, DocFX uses an environment parameter GIT_BRANCH set by Jenkins. This leads to broken links, since the variable is, for example, origin/dev when it should only be dev. This also prevents the links from being versioned, so documentation of old versions won't have the historic source code available.

But since this being Jenkins, there's nothing we can't do to solve this! In every build, there's an environment variable GIT_COMMIT provided which, as the name suggest, is the full hash of the checked out commit.

All you need to to is run this small PowerShell script to fix links in your generated Html files:

If you're looking for a bit more info on automating documentation generation, have a look at these two points:

  • The LightQuery package is configured to generate docs on build. Most importantly, there's a GenerateAndDeployDocs.ps1 script at the root doing all the work.
  • For publishing, I've created WebDocu. It's an Asp.Net Core app that lets you host online documentation with versioning and user management for non-public projects. You can take a look at it right here, a few of my projects have their docs publicly available.

Happy documenting!


Share this post


comments powered by Disqus

Dangl.Blog();
// Just 💗 Coding

Social Links