Home

Awesome

.NET CodeFactor GitHub issues GitHub repo size

Description

The most modular plugin-based documentation generator for your .NET libraries (currently officially supporting C# 9 and lower).

I'm writing a Bachelor's thesis about this project.

What does modular mean?

Generating documentation isn't for everyone. And those who do need it can have very specific needs. That's why ModularDoc is written in such a way, that almost everything is decoupled and can be replaced by you! But that is for the most extreme cases.

The most important feature is pluginability. Using plugins you chose how your documentation is generated. A plugin determines what is the required input, what is/are the output format(s), how the documentation is structured and processed. As of now, these are the available plugins:

Adding new plugins will extend the functionality of the tool. E.g., generate Markdown for DocFX, generate diagrams only, generate HTML...

There no simple way of describing ModularDoc, as it is very abstract, and defined by the plugins available.

Plugin: Markdown for Git

If you have no .xml files in your bin folder, then you can enable it per-project. You can follow this MSDN https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props, or modify the build property group in your csproj to something like this:

  <PropertyGroup Condition="'$(Configuration)|$(Platform)'=='Debug|AnyCPU'">
    <OutputPath>..\..\..\..\bin\Debug\Libraries\Core</OutputPath>
    <DocumentationFile>..\..\..\..\bin\Debug\Libraries\Core\ModularDoc.Printer.xml</DocumentationFile>
  </PropertyGroup>

Produced result:

Preview

screen

Performance

Comparison of ModularDoc's Markdown to Git plugin to Doxygen v1.9.5 and DocFX v2.59.4. Each tool was run four times on Windows OS via Windows PowerShell through the Measure-Command script block.

RunModularDocDoxygenDocFX
1864 ms3609 ms34268 ms
2968 ms1784 ms28662 ms
3869 ms1664 ms28681 ms
4846 ms1660 ms28681 ms
Average887 ms2179 ms30022 ms

How does it work?

Using ModularDoc.App you select one of the available plugins, go through its configuration steps, and finally save the configuration for further reuse.

Then you can open the previously created configuration either via ModularDoc.App, or using ModularDoc.CLI. The CLI application isn't polished yet, and only supports executing the provided path to the configuration:

./ModularDoc.CLI.exe PATH_TO_THE_CONFIG.mconf

How do I run the tool?

The tool does not have any releases at this time. You have to build it locally. You need at least .NET 6 SDK installed.

  1. Clone the repository git clone https://github.com/hailstorm75/ModularDoc.git
  2. Build the solution dotnet build src/ModularDoc.sln --configuration Release
  3. Run the bin/ModularDoc.App.exe

You can skip steps 2 and 3 if you are using an IDE such as Visual Studio 2019 (and higher) or JetBrains Rider, and use the regular build/run commands.

Next, you select the desired plugin and follow the steps until completion.

You can also run bin/ModularDoc.CLI.exe to execute the created configuration via the ModularDoc.App:

./bin/ModularDoc.CLI.exe PATH_TO_THE_CONFIG.mconf

Run it at your own risk, the code is still under development.

How to extend the tool?

The architecture is split into interfaces, components, and applications:

flowchart LR
    interface1[Interface]
    interface2[Interface]
    interface3[Interface]

    subgraph plugin1[Plugin]
      direction BT
      component1[Component]
      component2[Component]
      component3[Component]
    end

    subgraph plugin2[Plugin]
      direction BT
      component4[Component]
      component5[Component]
      component6[Component]
    end

    ModularDoc.App
    ModularDoc.CLI

    interface1 --> component1
    interface1 --> component4
    interface2 --> component2
    interface2 --> component5
    interface3 --> component3
    interface3 --> component6

    plugin1 --> ModularDoc.App
    plugin2 --> ModularDoc.App

    plugin1 --> ModularDoc.CLI
    plugin2 --> ModularDoc.CLI

External libraries