Skip to content

Latest commit

 

History

History
65 lines (41 loc) · 2.76 KB

21.living-documentation.md

File metadata and controls

65 lines (41 loc) · 2.76 KB

Living Documentation

In this chapter you will get familiar with Pitstop - Garage Management System sample project and the LivingDocumentation Analyzer dotnet tool.

Prerequisites
For this chapter you need the .NET Core SDK and git installed.

Getting a sample project

To start generating documentation, you need a project with enough code to generate something meaningful. For this you can use the Pitstop project. This project is created by Edwin van Wijk to showcase several concepts and techniques around DDD and microservices.

Pitstop - Garage Management System

Pitstop garage

The solution consist of several services that communicate using a message broker and web api's.

Pitstop solution architecture

The project gives enough object to start building some documentation.

You will be using a slightly modified version tailored for this workshop.

❯ git clone "https://github.com/eNeRGy164/pitstop.git"
❯ git checkout "docs"

The Living Documentation dotnet tool

To load the solution and start crawling through all projects, syntax trees and write tree walkers to get a feel for the code would take some time to write. This process has to be repeated everytime you want to analyze a different solution. To keep your documentation acurate, it should also be generated as part of you build pipeline. The performance impact of the compilation step makes you wait for 30-60 seconds everytime you analyze the code.

Considereing these points, the LivingDocumentation Analyzer dotnet tool was developed. It generates an intermediate json file that you generate when the source project changes, but after that you can use it as a source for you documentation renderer.

❯ dotnet tool install --global LivingDocumentation.Analyzer

Analyzing the Pitstop Solution

❯ livingdoc-analyze --solution "pitstop.sln" --output "pitstop.analyzed.json"

This can take about 30-60 seconds.

Living Documentation Analysis output generated in 31346ms at pitstop.analyzed.json

The json file will contain an array of all classes, methods, variables, types, if/else/case statements, etc...

If you want to inspect the json structure, add the --pretty switch to the command.

If there are issues like missing classes or unexpected output, add the --verbose switch to the command to see compile errors and other warnings.

Solution

You can find a prettyfied version of the output with the LivingDocumentation solution.