dotnet-cstomd 2.0.1

CsToMd

• CsToMd
  • Idea and Overview
  • Dotnet CLI tool
    • How to use
    • Build integration

Idea and Overview

The dotnet CLI tool 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 since v1.2.0:

• Converting the section outlined with //md{ and //md} comments int 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.

How to use

• Install the dotnet-cstomd globally from the nuget, e.g. in the shell of your choice dotnet tool install --global dotnet-cstomd --version 2.0.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 --global dotnet-cstomd --version 1.2.1 (the manifest file will be updated and later used for restore)

• Add the section to you 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 the build:

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

You may create a helper build_the_docs file and store the command there.

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