https://github.com/dadhi/cstomd

Visual Studio extension and dotnet CLI tool to generate the Markdown Docs from the C# Tests keeping your Docs and Tests in sync!
https://github.com/dadhi/cstomd

cli documentation documentation-generator documentation-tool dotnet dotnet-tool extension filegenerator markdown runnable samples tools visualstudio2017

Last synced: 6 months ago
JSON representation

Visual Studio extension and dotnet CLI tool to generate the Markdown Docs from the C# Tests keeping your Docs and Tests in sync!

• Host: GitHub
• URL: https://github.com/dadhi/cstomd
• Owner: dadhi
• License: mit
• Created: 2018-09-13T11:29:04.000Z (about 7 years ago)
• Default Branch: master
• Last Pushed: 2025-04-13T21:15:34.000Z (6 months ago)
• Last Synced: 2025-04-15T14:56:04.979Z (6 months ago)
• Topics: cli, documentation, documentation-generator, documentation-tool, dotnet, dotnet-tool, extension, filegenerator, markdown, runnable, samples, tools, visualstudio2017
• Language: C#
• Homepage:
• Size: 1.02 MB
• Stars: 43
• Watchers: 4
• Forks: 5
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

README

          
# CsToMd

- [CsToMd](#cstomd)

  - [Idea and Overview](#idea-and-overview)

  - [Dotnet CLI tool](#dotnet-cli-tool)

    - [Ad-hoc document generation](#ad-hoc-document-generation)

    - [Build integration](#build-integration)

  - [Visual Studio extension](#visual-studio-extension)

    - [How to use](#how-to-use)

## Idea and Overview

[![NuGet Badge](https://img.shields.io/nuget/v/dotnet-cstomd.svg)](https://nuget.org/packages/dotnet-cstomd)

The [dotnet CLI tool](https://www.nuget.org/packages/dotnet-cstomd) to convert C# file with Unit Tests into the [Markdown](https://guides.github.com/features/mastering-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](https://github.com/dadhi/DryIoc/tree/master/docs/DryIoc.Docs) 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](https://gist.github.com/pierrejoubert73/902cc94d79424356a8d20be2b382e1ab).

- 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](https://www.nuget.org/packages/dotnet-cstomd) is a [dotnet CLI tool](https://docs.microsoft.com/en-us/dotnet/core/tools/). 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**.

![VSCode usage](https://github.com/dadhi/CsToMd/blob/master/screen3.png?raw=true)

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

    ```xml

    

        

    

    

        

    

    ```

    You may check the DryIoc [documentation project file](https://github.com/dadhi/DryIoc/blob/6f466ee1b4fde548c7211ecb0a54655011f69e57/docs/DryIoc.Docs/DryIoc.Docs.csproj#L26) 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](https://docs.microsoft.com/en-us/dotnet/core/tools/local-tools-how-to-use#:~:text=Create%20a%20manifest%20file,-To%20install%20a&text=The%20output%20indicates%20successful%20creation%20of%20the%20file.&text=The%20template%20%22Dotnet%20local%20tool%20manifest%20file%22%20was%20created%20successfully.&text=The%20tools%20listed%20in%20a,the%20one%20that%20contains%20the%20.) 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:

![Screenshot](screenshot_vsix_v2_1_0.png)

### How to use

- Install [the extension](https://marketplace.visualstudio.com/items?itemName=dadhi.cstomd123) directly from the marketplace in Visual Studio or download the extension vsix file from the [release page](https://github.com/dadhi/CsToMd/releases/tag/v2.1.0).

- 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