CsToMd

• CsToMd
  • Idea and Overview
  • Dotnet CLI tool
    • Ad-hoc document generation
    • Build integration

Idea and Overview

The dotnet CLI tool to convert C# file with Unit Tests into the Markdown documentation.

The idea is to have a normal C# .cs file with the special comments /*md, md*/, and //md which will be stripped when converting the file into the respective Markdown .md file. There are couple of additional features but this is basically it.

Now you have the documentation always up-to-date with the runnable samples in the normal .NET Test library project with NUnit, XUnit, etc.

You may check the DryIoc documentation project for the real-world case example.

The additional features since v1.2.0:

• Converting the section outlined with //md{ and //md} comments into the collapsed markdown details.
• The optional cstomd.config file in the folder with the lines starters to be removed completely from the generated documentation file.

Dotnet CLI tool

The dotnet-cstomd is a dotnet CLI tool. It may be called from the command line and from the MSBuild scripts (enabling the document generation in the build pipeline).

I addition the dotnet tool enables the documentation development in the Visual Studio Code.

Ad-hoc document generation

• Install the dotnet-cstomd globally from the nuget, e.g. in the shell of your choice dotnet tool install --global dotnet-cstomd --version 1.2.1. Now you can invoke cstomd MyClass.cs directly and get the MyClass.md output.

Build integration

• Switch to your project: cd path\to\MyProject

• Add the tool manifest file: dotnet new tool-manifest

• Install the tool: dotnet tool install dotnet-cstomd --version 1.2.1 --roll-forward (the manifest file will be updated and later used for restore)

• Add the section to your project:

  <ItemGroup>
      <DocFile Include="**\*.cs" />
  </ItemGroup>
  
  <Target Name="MdGenerate" BeforeTargets="BeforeBuild">
      <Exec WorkingDirectory="$(ProjectDir)" Command="dotnet cstomd %(DocFile.Identity)" />
  </Target>

  You may check the DryIoc documentation project file for the real-world case example.

• You may run the document generation target without the rest of the build:

 dotnet msbuild -target:MdGenerate path\to\MyProject\MyProject.csproj

You may create a helper shell script with the command above.

Here is the MS tutorial for installing and using the local tools.