CsToMd

Overview

The dotnet CLI tool and Visual Studio extension to generate the Markdown documentation file from the C# file.

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 in 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.

Visual Studio extension

This extension for Visual Studio 2019+ contains the CustomTool File Generator.

When applied to the C# source file it looks like this:

The generated result:

How to use

• Install the extension directly from the markerplace in Visual Studio or download the extension vsix file from the release page.
• In properties of your .cs file set the CustomTool property to CsToMd.
• Save the .cs file
• Check the generated .md file under the .cs file in Solution Explorer

Dotnet CLI tool

The dotnet-cstomd is a dotnet CLI tool providing the same functionality as a Visual Studio extension plus it may be called from the command line and from the MSBuild enabling the document generation in the build pipeline.

In 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 (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.