98 lines
3.4 KiB
Markdown
98 lines
3.4 KiB
Markdown
# Diagram templates
|
|
|
|
<!-- toc -->
|
|
|
|
* [Diagram template syntax](#diagram-template-syntax)
|
|
* [Adding templates to the configuration file](#adding-templates-to-the-configuration-file)
|
|
* [Adding diagram to configuration from a template](#adding-diagram-to-configuration-from-a-template)
|
|
* [Builtin templates](#builtin-templates)
|
|
|
|
<!-- tocstop -->
|
|
|
|
When working with large codebases, it is often necessary to create diagram
|
|
configurations for a large number of classes or groups of classes.
|
|
|
|
Diagram templates feature makes this easier, by allowing to define (or use
|
|
one of the builtin) templates and generate using them any number of diagram
|
|
configurations. Diagram templates can be defined using Jinja like template
|
|
syntax (current renderer implementation is
|
|
[inja](https://github.com/pantor/inja)).
|
|
|
|
## Diagram template syntax
|
|
Diagram templates are defined as part of the configuration file using the
|
|
following YAML node:
|
|
|
|
```yaml
|
|
diagram_templates:
|
|
# Name of the template
|
|
parents_hierarchy_tmpl:
|
|
# Description of the template
|
|
description: Generate class parents inheritance diagram
|
|
# Diagram type
|
|
type: class
|
|
# Template definition - it has to be valid YAML after it is rendered
|
|
template: |
|
|
{{ diagram_name }}:
|
|
type: class
|
|
{% if exists("glob") %}
|
|
glob: [{{ glob }}]
|
|
{% endif %}
|
|
{% if exists("using_namespace") %}
|
|
using_namespace: {{ using_namespace }}
|
|
{% endif %}
|
|
include:
|
|
parents: [{{ class_name }}]
|
|
namespaces: [{{ namespace_names }}]
|
|
relationships:
|
|
- inheritance
|
|
exclude:
|
|
access: [public, protected, private]
|
|
plantuml:
|
|
before:
|
|
- left to right direction
|
|
```
|
|
|
|
## Adding templates to the configuration file
|
|
Diagram templates can be added directly to the `.clang-uml` configuration file,
|
|
under a `diagram_templates:` key. However, for practical reasons its better
|
|
to keep diagram template definitions in a separate Yaml file, and reference
|
|
it in the configuration file using `include!` directive, e.g.:
|
|
|
|
```yaml
|
|
diagram_templates:
|
|
include!: .clang-uml-templates
|
|
```
|
|
|
|
## Adding diagram to configuration from a template
|
|
To add a new diagram definition to the configuration file based on the template,
|
|
simply call the `clang-uml` using the following options:
|
|
|
|
```bash
|
|
clang-uml --add-diagram-from-template parents_hierarchy_tmpl \
|
|
--template-var class_name=clanguml::config::include_diagram \
|
|
--template-var namespace_names=clanguml \
|
|
--template-var diagram_name=abcd \
|
|
--template-var "glob=src/config/*.cc" \
|
|
--template-var using_namespace=clanguml::config
|
|
```
|
|
|
|
To see what variables are necessary to provide for a template, the template
|
|
can be printed from the command line using the following command:
|
|
|
|
```bash
|
|
clang-uml --show-template parents_hierarchy_tmpl
|
|
```
|
|
|
|
## Builtin templates
|
|
`clang-uml` has some predefined templates, which can be used directly. If the
|
|
users configuration file defines another template with a name which already
|
|
exists as built-in template it will override the predefined templates.
|
|
|
|
Currently, the following templates are built-in:
|
|
* `parents_hierarchy_tmpl` - generate inheritance hierarchy diagram including
|
|
parents of a specified class
|
|
* `subclass_hierarchy_tmpl` - generate inheritance hierarchy diagram including
|
|
c children of a specified class
|
|
* `class_context_tmpl` - generate diagram including all classes in direct
|
|
relationship (of any kind) with a specific class
|