{"id":13777260,"url":"https://github.com/hailstorm75/ModularDoc","last_synced_at":"2025-05-11T11:33:10.470Z","repository":{"id":36970535,"uuid":"248785839","full_name":"hailstorm75/ModularDoc","owner":"hailstorm75","description":"Modular documentation generator for .NET libraries. Currently supporting Markdown only for GitHub, GitLab, and Bitbucket","archived":false,"fork":false,"pushed_at":"2023-09-21T23:21:47.000Z","size":2020,"stargazers_count":92,"open_issues_count":13,"forks_count":8,"subscribers_count":4,"default_branch":"unstable","last_synced_at":"2024-02-15T03:34:33.888Z","etag":null,"topics":["bitbucket","csharp","documentation","documentation-generator","documentation-tool","dotnet","github","gitlab","markdown","netcore","netframework","netstandard","reflection","wiki"],"latest_commit_sha":null,"homepage":"","language":"C#","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hailstorm75.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2020-03-20T15:12:29.000Z","updated_at":"2024-02-13T22:15:44.000Z","dependencies_parsed_at":"2024-01-13T11:12:57.467Z","dependency_job_id":"21d8c1cf-59e2-4b09-bee6-5501aacf6b6d","html_url":"https://github.com/hailstorm75/ModularDoc","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hailstorm75%2FModularDoc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hailstorm75%2FModularDoc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hailstorm75%2FModularDoc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hailstorm75%2FModularDoc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hailstorm75","download_url":"https://codeload.github.com/hailstorm75/ModularDoc/tar.gz/refs/heads/unstable","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225043088,"owners_count":17411927,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bitbucket","csharp","documentation","documentation-generator","documentation-tool","dotnet","github","gitlab","markdown","netcore","netframework","netstandard","reflection","wiki"],"created_at":"2024-08-03T18:00:40.505Z","updated_at":"2024-11-17T13:30:35.784Z","avatar_url":"https://github.com/hailstorm75.png","language":"C#","readme":"[![.NET](https://github.com/hailstorm75/ModularDoc/actions/workflows/dot-core.yml/badge.svg)](https://github.com/hailstorm75/ModularDoc/actions/workflows/dot-core.yml) [![CodeFactor](https://www.codefactor.io/repository/github/hailstorm75/modulardoc/badge)](https://www.codefactor.io/repository/github/hailstorm75/modulardoc) ![GitHub issues](https://img.shields.io/github/issues/hailstorm75/ModularDoc) ![GitHub repo size](https://img.shields.io/github/repo-size/hailstorm75/ModularDoc)\n\n# Description\nThe most modular plugin-based documentation generator for your .NET libraries (currently officially supporting C# 9 and lower).\n\n[I'm writing a Bachelor's thesis about this project](https://github.com/hailstorm75/ModularDoc.Thesis).\n\n## What does modular mean?\n\nGenerating 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.\n\nThe 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:\n\n - Markdown for Git - generates Markdown documentation for GitHub, GitLab, and Bitbucket\n \nAdding new plugins will extend the functionality of the tool. E.g., generate Markdown for DocFX, generate diagrams only, generate HTML...\n\nThere no simple way of describing ModularDoc, as it is very abstract, and defined by the plugins available.\n\n### Plugin: Markdown for Git\n\n- This plugin uses reflection for gathering types and their members from assemblies and reads the XML documentation generated on your project build\n- The generated output is a Markdown file per type (interface, class, struct, record, enum...)\n- It also provides inheritance diagrams via MermaidJS\n- The structure of the documentation is inspired by Doxygen, and is not configurable\n- The file structure of the generated files can be configured to be flat, or structured into folders\n\nIf you have no *.xml* files in your bin folder, then you can enable it per-project.\nYou can follow this MSDN [https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props](https://learn.microsoft.com/en-us/dotnet/core/project-sdk/msbuild-props#documentationfile), or modify the build property group in your **csproj** to something like [this](https://github.com/hailstorm75/ModularDoc/blob/8656b3c338a7373d035ed41ab8f004b492e0ae70/src/Libraries/Core/ModularDoc.Printer/ModularDoc.Printer.csproj#L13):\n\n```xml\n  \u003cPropertyGroup Condition=\"'$(Configuration)|$(Platform)'=='Debug|AnyCPU'\"\u003e\n    \u003cOutputPath\u003e..\\..\\..\\..\\bin\\Debug\\Libraries\\Core\u003c/OutputPath\u003e\n    \u003cDocumentationFile\u003e..\\..\\..\\..\\bin\\Debug\\Libraries\\Core\\ModularDoc.Printer.xml\u003c/DocumentationFile\u003e\n  \u003c/PropertyGroup\u003e\n```\n\n#### Produced result:\n - [Generated for source code](https://github.com/hailstorm75/ModularDoc/tree/unstable/sourceWiki) - the documentation is stored in the repository right next to your source code\n - [Generated for the GitHub Wiki](https://github.com/hailstorm75/ModularDoc/wiki) - GitHub has poor Wiki management, each generated Markdown file has to be manually uploaded. **The generated examples here are out of date and contain fixed bugs. Use it only as a visual example of the result**\n\n#### Preview\n\n![screen](https://user-images.githubusercontent.com/16069996/153456188-5f9678cf-efc8-4764-8bc4-6e5b1c034c0d.gif)\n\n#### Performance\n\nComparison 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.\n\n| Run           | ModularDoc     | Doxygen     | DocFX        |\n| ------------- | -------------- | ----------- | ------------ |\n| 1             |         864 ms |     3609 ms |     34268 ms |\n| 2             |         968 ms |     1784 ms |     28662 ms |\n| 3             |         869 ms |     1664 ms |     28681 ms |\n| 4             |         846 ms |     1660 ms |     28681 ms |\n| **Average**   |     **887 ms** | **2179 ms** | **30022 ms** |\n\n## How does it work?\n\nUsing **ModularDoc.App** you select one of the available plugins, go through its configuration steps, and finally save the configuration for further reuse.\n\nThen 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:\n\n`./ModularDoc.CLI.exe PATH_TO_THE_CONFIG.mconf`\n\n## How do I run the tool?\n\nThe tool does not have any releases at this time. You have to build it locally. You need at least .NET 6 SDK installed.\n\n 1. Clone the repository `git clone https://github.com/hailstorm75/ModularDoc.git`\n 2. Build the solution `dotnet build src/ModularDoc.sln --configuration Release`\n 3. Run the `bin/ModularDoc.App.exe`\n\nYou 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.\n\nNext, you select the desired plugin and follow the steps until completion.\n\nYou can also run `bin/ModularDoc.CLI.exe` to execute the created configuration via the **ModularDoc.App**:\n\n`./bin/ModularDoc.CLI.exe PATH_TO_THE_CONFIG.mconf`\n\nRun it at your own risk, the code is still under development.\n\n## How to extend the tool?\n\nThe architecture is split into interfaces, components, and applications:\n\n```mermaid\nflowchart LR\n    interface1[Interface]\n    interface2[Interface]\n    interface3[Interface]\n\n    subgraph plugin1[Plugin]\n      direction BT\n      component1[Component]\n      component2[Component]\n      component3[Component]\n    end\n\n    subgraph plugin2[Plugin]\n      direction BT\n      component4[Component]\n      component5[Component]\n      component6[Component]\n    end\n\n    ModularDoc.App\n    ModularDoc.CLI\n\n    interface1 --\u003e component1\n    interface1 --\u003e component4\n    interface2 --\u003e component2\n    interface2 --\u003e component5\n    interface3 --\u003e component3\n    interface3 --\u003e component6\n\n    plugin1 --\u003e ModularDoc.App\n    plugin2 --\u003e ModularDoc.App\n\n    plugin1 --\u003e ModularDoc.CLI\n    plugin2 --\u003e ModularDoc.CLI\n```\n\n- **Interfaces** define abstract contracts that must be implemented by components. Interfaces allow components to communicate with each other without tight coupling. E.g., type and member provider is an abstract interface - no concrete information on how said data is retrieved, only that it is provided\n- **Components** are concrete implementations of interfaces. E.g., reflection-based type and member provider - this component uses reflection to analyze assemblies and provide type and member data\n- **Plugins** are bundles of concrete components. Plugins provide configuration steps for said components and an endpoint for executing them\n- **Applications** are consumers of **plugins** that either display them to the user for further configuration or execute them based on the provided configuration\n\n# External libraries\n\n- [Avalonia UI](https://github.com/AvaloniaUI/Avalonia) for a cross-platform GUI\n- [Avalonia Behaviors](https://github.com/wieslawsoltes/AvaloniaBehaviors) for extending GUI building tools of Avalonia UI\n- [DynamicData](https://github.com/reactivemarbles/DynamicData) for awesome reactive collections\n- [FluentAvaloniaUI](https://github.com/amwx/FluentAvalonia) for the modern FluentUI look\n- [Icons.Avalonia](https://github.com/Projektanker/Icons.Avalonia) for adding font-awesome icons support to Avalonia UI\n- [xUnit](https://github.com/xunit/xunit) for unit testing\n- [Autofac](https://github.com/autofac/Autofac) for dependency injection\n- [dnlib](https://github.com/0xd4d/dnlib) for retrieving types from assemblies\n","funding_links":[],"categories":["Samples and Projects"],"sub_categories":["Documents"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhailstorm75%2FModularDoc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhailstorm75%2FModularDoc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhailstorm75%2FModularDoc/lists"}