CsToMd

KO | EN

gitlite — search

#javascript #typescript #golang #go #android #machine-learning #rust #deep-learning #docker #macos #awesome #cli #vue #open-source

(★ 47)

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

CsToMd Latest Version Download

Download Latest Version (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# 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
    <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](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](https://raw.githubusercontent.com/dadhi/CsToMd/master/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

CsToMd

CsToMd Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

CsToMd

CsToMd Latest Version Download

Today's picks

Was this content helpful?

Recent Feedback

Download README