In this repository you can find all tools and libraries that facilitate use of P3 Model in .net.
P3 Model is a tool to automatically generate documentation from your source code.
Generated documentation is based on information already present in the code and additional metadata added with annotations and JSON or Markdown files.
If you haven't check out main P3 Model repository then we strongly encourage you to do so.
Our goal is to provide visualization of the developed system including all important aspects:
- domain model (processes, modules, building blocks, etc.)
- technology solutions (deployable units, layers, api, types, etc.)
- people working on it (teams responsibilities, business ownership, etc.)
The visualization is based on parsed source code augmented with metadata (from P3Model.Annotations
library).
You can see the idea in this video:
Now it's only very simple, fixed set of Markdown pages with Mermaid diagrams. It's MVP.
In the future we plan to provide dynamic visualization tool (with zooming, filtering elements and relations, ad hoc diagrams, etc.).
- Add P3Model.Annotations package to each project you want to add metadata to.
- Add appropriate attributed to your code. Full list of annotations with usage examples you can find here.
- Create console application.
- Add P3Model.Parser package.
- Configure Parser in
Program.cs
like that:await P3 .Product(product => product .UseName("YOUR_SYSTEM_NAME")) .Repositories(repositories => repositories .Use("REPOSITORY_PATH")) .Analyzers(analyzers => analyzers .UseDefaults(options => options .TreatNamespacesAsDomainModules(namespaces => namespaces .RemoveNamespacePart("PART_TO_REMOVE")))) .OutputFormat(formatters => formatters .UseMermaid(options => options .Directory("MERMAID_OUTPUT_PATH") .UseDefaultPages()) .UseJson(options => options .File("JSON_OUTPUT_PATH"))) .LogLevel(LogEventLevel.Verbose) .Analyze();
- Run parser from command line or your IDE.
- Integrate Parser with your CI pipeline to update documentation on every commit.
Here is example with GitHub Action:name: Generate P3 documentation on: push: branches: - main jobs: generate-p3-docs: runs-on: ubuntu-latest permissions: contents: write steps: - name: Checkout repository uses: actions/checkout@v4 - name: Restore packages run: dotnet restore - name: Run P3 Parser run: dotnet run --project Docs/P3/DocsGenerator/DocsGenerator.csproj - name: Add, Commit & Push changes uses: stefanzweifel/git-auto-commit-action@v5 with: commit_message: "P3 docs updated"
If you'd like to see P3 Model in bigger code base check DDD Starter for .net.
Join us and help building P3 Model. Let's solve the problem of outdated and useless documentation together.
To start contributing you can:
- join our discussions in main repository
- open issue in this repository and write your proposition or question
This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License.