Skip to content

Generate documentation based on your dotnet source code!

License

Notifications You must be signed in to change notification settings

eNeRGy164/LivingDocumentation

Repository files navigation

Living Documentation

Azure DevOps builds Azure DevOps tests

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 Nuget
Analyzer Tool Preview Azure Artifacts

Presentation

Watch the session given at NDC London 2023 that covers examples using this tool:

Use your source code to document your application - Michaël Hompus - NDC London 2023

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:

  1. 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.
  2. 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.
  3. 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.