LivingDocumentation
LivingDocumentation copied to clipboard
Generate documentation based on your dotnet source code!
Living Documentation
Living Documentation allows you to analyze your dotnet source code and generate comprehensive documentation for your stakeholders. It's a powerful tool that bridges the gap between code and documentation, ensuring that your documentation is always up-to-date with your source code.
Features
- Analyzer: A tool to analyze dotnet projects or solutions.
- Libraries: Assists in generating applications that can create plain text files such as MarkDown, AsciiDoc, PlantUML, Mermaid, and more.
Packages
Package | Type | Status |
---|---|---|
Analyzer Tool | Released | |
Analyzer Tool | Preview |
Presentation
Watch the session given at NDC London 2023 that covers examples using this tool:
Getting Started
Prerequisites
- Dotnet 6.0 SDK or newer.
Installation
Install the analyzer as a dotnet global tool:
dotnet tool install --global LivingDocumentation.Analyzer
Generating Documentation
Using LivingDocumentation to generate documentation involves a three-step process:
- Analyze Source Code: Run the LivingDocumentation.Analyzer with your Visual Studio solution file as input. This will generate an intermediate JSON file containing detailed information about your source code.
- Develop Renderers: Create a custom "render application" to interpret the JSON file and generate various views on your source code, such as class diagrams or sequence diagrams.
- Output Documentation: Export your findings in text-based formats like Markdown, AsciiDoc, PlantUML, Mermaid, etc.
Both during local development, as during your CI&CD pipeline, can follow the same flow.
Local Development
The analysis of a solution might take some time. Therefore, an intermediate JSON file is created to speed up the documentation generation process. This ensures a fast feedback loop when developing your renderers.
Develop Your Own Renderers
A renderer application can be as simple as a command line tool that takes in the generated JSON files, makes conclusions based on the type information and writes this to a plain text file format.
To get started quickly, you should make a dependency on 2 NuGet packages in your project:
- LivingDocumentation.RenderExtensions: Contains extension methods and dependencies for serialized analysis.
- LivingDocumentation.Json: Contains JSON serializers and contract resolvers.
More details
More details can be found in the Guide.
Dive Deeper
For more detailed examples and advanced use cases, refer to the second chapter of the LivingDocumentation.Workshop.
Contributing
You are welcome to contribute! Feel free to create issues or pull requests.
License
This project is licensed under the MIT License.