dotnet-cstomd 2.1.0

CsToMd

• CsToMd
  • Idea and Overview
  • Dotnet CLI tool
    • Ad-hoc document generation
    • Build integration
  • Visual Studio extension
    • How to use

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 a 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:

• Directive to automatically wrap code in code fence with the optional language, e.g. add //md code:csharp, or just //md code: to add fences, and //md code:-- to stop adding fences. The directive may be used multiple times through the file.
• 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.

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:

How to use

• Install the extension directly from the marketplace 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