Auto-document dotnet CLI tool via dynamically generated markdown readme fragments

Every time I create a new CLI tool, I face the challenge of keeping the project and package readme (for dotnet tools like dotnet-trx) up to date with the evolving tool itself.

It’s annoying and repetitive (run with --help, copy-paste) and it’s not uncommon to end up with stale docs.

Here’s one way to automate the whole thing so you can just focus on making your tool awesome.

First, have your project emit the help to a text file, say help.md:

   <Target Name="RenderHelp" AfterTargets="Build" Condition="$(DesignTimeBuild) != 'true'" >
     <WriteLinesToFile Lines="```shell" Overwrite="true" File="help.md" />
     <Exec Command="dotnet run --no-build -- --help &gt;&gt; help.md" 
           EnvironmentVariables="NO_COLOR=true" />
     <WriteLinesToFile Lines="```" Overwrite="false" File="help.md" />
   </Target>

NOTE: I’m passing NO_COLOR to disable Spectre console colors in the output.

Next, if you only need to include the help in the package readme, include the auto-generated help file using the following syntax:

   # My Awesome Tool
   Tool options: 
   <!-- include help.md -->

NOTE: the file path must be relative to the including file.

Then install NuGetizer to perform the packing instead, which supports this markdown inclusion feature via the package readme.

NOTE: nugetizer is pretty much 100% compatible with SDK pack, in particular for dotnet tools, unless you have fancy customization of the package contents via MSBuild or nuspec.

At pack time, nugetizer will resolve the includes and expand them in the package readme.

If you also want to keep a repository readme up-to-date, you can use a GitHub workflow that automatically updates the readme with the latest help output after a commit to the main branch:

1. Create a project readme.md that uses +Mᐁ includes, using the same syntax above for package readme:

    # My Awesome Tool
    Tool options: 
    <!-- include src/dotnet-trx/help.md -->
   

   NOTE: the path is now relative to the root of the repository, as an example.

2. Set up a github workflow that keeps the readme up-to-date with changes in the auto-generated help file:

    on: 
      push:
        branches:
          - 'main'
        paths:
          - '**.md'
   
    jobs:
      includes:
        runs-on: ubuntu-latest
        steps:
          - name: 🤘 checkout
            uses: actions/checkout@v2
   
          - name: +Mᐁ includes
            uses: devlooped/actions-include@v1
   
          - name: ✍ pull request
            uses: peter-evans/create-pull-request@v6
            with:
              add-paths: '**.md'
              base: main
              branch: markdown-includes
              delete-branch: true
              labels: docs
              commit-message: +Mᐁ includes
              title: +Mᐁ includes
              body: +Mᐁ includes
   

3. Merge the docs PR whenever it shows up, and you’re done!

Real example:

• PR that adds auto-doc help file
• Automated PR that updates main readme

If you use the awesome Spectre.Console project for your CLI, you need to disable all styles when NO_COLOR is specified, to avoid having style ANSI codes in the output:

var app = new CommandApp();
// ...
app.Configure(config =>
{
  if (Environment.GetEnvironmentVariables().Contains("NO_COLOR"))
      config.Settings.HelpProviderStyles = null;
});

Happy coding! 🚀𝕩