diff --git a/CHANGELOG.md b/CHANGELOG.md index b2dd19ff..a43daf91 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,9 +1,11 @@ # CHANGELOG + * Added MermaidJS diagram generators (#27) + ### 0.3.9 * Added `from_to` and `to` location constraints to sequence diagrams (#154) * Fixed 'else if' statement generation in sequence diagrams (#81) - * Implemented removal of redundant dependency relationhips (#28) + * Implemented removal of redundant dependency relationships (#28) * Add option to disable generation of dependency relation to template arguments (#141) * Added configuration file validation (#57) diff --git a/README.md b/README.md index 5edf5ccd..8fd3f0e9 100644 --- a/README.md +++ b/README.md @@ -13,7 +13,8 @@ YAML configuration files. The main idea behind the project is to easily maintain up-to-date diagrams within a code-base or document legacy code. The configuration file or files for `clang-uml` define the types and contents of each generated diagram. -The diagrams can be generated in [PlantUML](https://plantuml.com) and JSON formats. +The diagrams can be generated in [PlantUML](https://plantuml.com), +[MermaidJS](https://mermaid.js.org/) and JSON formats. `clang-uml` currently supports C++ up to version 17 with partial support for C++ 20. @@ -35,8 +36,8 @@ Main features supported so far include: * Template specialization and instantiation based on deduced context - [_example_](docs/test_cases/t00062.md) * Relationship inference from C++ containers and smart pointers - [_example_](docs/test_cases/t00007.md) * Diagram content filtering based on namespaces, elements and relationships - [_example_](docs/test_cases/t00040.md) - * Optional package generation from namespaces - [_example_](docs/test_cases/t00036.md) - * Optional package generation from subdirectories - [_example_](docs/test_cases/t00065.md) + * Optional package generation from namespaces (only PlantUML) - [_example_](docs/test_cases/t00036.md) + * Optional package generation from subdirectories (only PlantUML) - [_example_](docs/test_cases/t00065.md) * Interactive links to online code to classes, methods and class fields in SVG diagrams - [_example_](https://raw.githubusercontent.com/bkryza/clang-uml/master/docs/test_cases/t00002_class.svg) * Support for plain C99/C11 code (struct and units relationships) - [_example_](docs/test_cases/t00057.md) * C++20 concept constraints - [_example_](docs/test_cases/t00059.md) @@ -370,17 +371,17 @@ results in the following diagram (via PlantUML) based on include directives in t ### Default mappings -| UML | PlantUML | -| ---- | --- | -| Inheritance | ![extension](docs/img/puml_inheritance.png) | -| Association | ![association](docs/img/puml_association.png) | -| Dependency | ![dependency](docs/img/puml_dependency.png) | -| Aggregation | ![aggregation](docs/img/puml_aggregation.png) | -| Composition | ![composition](docs/img/puml_composition.png) | -| Template specialization/instantiation | ![specialization](docs/img/puml_instantiation.png) | -| Nesting (inner class/enum) | ![nesting](docs/img/puml_nested.png) | -| Include (local) | ![association](docs/img/puml_association.png) | -| Include (system) | ![dependency](docs/img/puml_dependency.png) | +| UML | PlantUML | MermaidJS | +| ---- | --- |------------------------------------------------| +| Inheritance | ![extension](docs/img/puml_inheritance.png) | ![extension](docs/img/mermaid_inheritance.png) | +| Association | ![association](docs/img/puml_association.png) | ![association](docs/img/mermaid_association.png) | +| Dependency | ![dependency](docs/img/puml_dependency.png) | ![dependency](docs/img/mermaid_dependency.png) | +| Aggregation | ![aggregation](docs/img/puml_aggregation.png) | ![aggregation](docs/img/mermaid_aggregation.png) | +| Composition | ![composition](docs/img/puml_composition.png) | ![composition](docs/img/mermaid_composition.png) | +| Template specialization/instantiation | ![specialization](docs/img/puml_instantiation.png) | ![specialization](docs/img/mermaid_instantiation.png) | +| Nesting (inner class/enum) | ![nesting](docs/img/puml_nested.png) | ![nesting](docs/img/mermaid_nested.png) | +| Include (local) | ![association](docs/img/puml_association.png) | ![association](docs/img/mermaid_association.png) | +| Include (system) | ![dependency](docs/img/puml_dependency.png) | ![dependency](docs/img/mermaid_dependency.png) | ### Diagram content filtering @@ -433,6 +434,7 @@ This project relies on the following great tools: * [Clang LibTooling](https://clang.llvm.org/docs/LibTooling.html) - a C++ library for creating tools based on Clang * [PlantUML](https://plantuml.com/) - language and diagram for generating UML diagrams +* [MermaidJS](https://mermaid.js.org/) - JavaScript based diagramming and charting tool * [Catch2](https://github.com/catchorg/Catch2) - C++ unit test framework * [glob](https://github.com/p-ranav/glob) - Unix style path expansion for C++ * [indicators](https://github.com/p-ranav/indicators) - Activity indicators for modern C++ diff --git a/docs/architecture.md b/docs/architecture.md index 24cd6415..2367eb42 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -134,12 +134,14 @@ Diagram generators convert the `clang-uml`'s internal UML model into actual diagram in one of the supported formats: - PlantUML +- MermaidJS - JSON Each diagram generator extends a common interface appropriate for the selected output format, i.e.: - [PlantUML](classclanguml_1_1common_1_1generators_1_1plantuml_1_1generator.html) +- [MermaidJS](classclanguml_1_1common_1_1generators_1_1mermaid_1_1generator.html) - [JSON](classclanguml_1_1common_1_1generators_1_1json_1_1generator.html) and renders the output to a file. For each diagram type there is a separate diff --git a/docs/common_options.md b/docs/common_options.md index d8f77ac8..f2535835 100644 --- a/docs/common_options.md +++ b/docs/common_options.md @@ -4,7 +4,7 @@ * [Overall configuration file structure](#overall-configuration-file-structure) * [Translation unit glob patterns](#translation-unit-glob-patterns) -* [PlantUML custom directives](#plantuml-custom-directives) +* [Custom directives](#custom-directives) * [Adding debug information in the generated diagrams](#adding-debug-information-in-the-generated-diagrams) * [Resolving include path and compiler flags issues](#resolving-include-path-and-compiler-flags-issues) * [Use '--query-driver' command line option](#use---query-driver-command-line-option) @@ -63,9 +63,10 @@ For small projects, the `glob` property can be omitted, which will result in `cl from `compile_commands.json` for the diagram. However for large projects, constraining the number of translation units for each diagram to absolute minimum will significantly decrease the diagram generation times. -## PlantUML custom directives -In case it's necessary to add some custom PlantUML declarations before or after the generated diagram content, -it can be achieved simply using the `plantuml` configuration properties, for instance: +## Custom directives +In case it's necessary to add some custom PlantUML or MermaidJS declarations +before or after the generated diagram content, it can be achieved simply using +the `plantuml` or `mermaid` configuration properties, for instance for PlantUML: ```yaml plantuml: @@ -75,23 +76,37 @@ it can be achieved simply using the `plantuml` configuration properties, for ins - note left of {{ alias("ns1::ns2::MyClass") }} This is my class. ``` -These directive are useful for instance for adding notes to elements in the diagrams or customizing diagram layout -or style. +or for MermaidJS: -Please note that when referring to diagram elements in the PlantUML directives, they must be added using Jinja -templates `alias` command as in the example above. +```yaml + mermaid: + before: + - direction LR + after: + - note for {{ alias("ns1::ns2::MyClass") }} "This is my class." +``` -More options can be found in the official PlantUML [documentation](https://plantuml.com/). +These directive are useful for instance for adding notes to elements in the +diagrams or customizing diagram layout or style. + +Please note that when referring to diagram elements in the PlantUML directives, +they must be added using Jinja templates `alias` command as in the example above. + +More options can be found in the official docs for each respective generator: + * [PlantUML](https://plantuml.com/) + * [MermaidJS](https://mermaid.js.org/intro/) ## Adding debug information in the generated diagrams -Sometimes it is useful for debugging issues with the diagrams to have information on the exact source location, -from which given declaration or call expression was derived. By adding option: +Sometimes it is useful for debugging issues with the diagrams to have information +on the exact source location, from which given declaration or call expression was +derived. By adding option: ```yaml debug_mode: true ``` -the generated PlantUML diagram will contain comments before each line containing the source location of the +the generated PlantUML diagram will contain comments before each line containing +the source location of the specific diagram element. ## Resolving include path and compiler flags issues diff --git a/docs/configuration_file.md b/docs/configuration_file.md index 1b0fe40a..77b39b64 100644 --- a/docs/configuration_file.md +++ b/docs/configuration_file.md @@ -54,7 +54,10 @@ * `plantuml` - verbatim PlantUML directives which should be added to a diagram * `before` - list of directives which will be added before the generated diagram * `after` - list of directives which will be added after the generated diagram - +* `mermaid` - verbatim MermaidJS directives which should be added to a diagram + * `before` - list of directives which will be added before the generated diagram + * `after` - list of directives which will be added after the generated diagram + * ## Example complete config ```yaml @@ -138,6 +141,10 @@ diagrams: # Add this line to the beginning of the resulting puml file before: - 'title clang-uml class diagram model' + mermaid: + # Add this line at the end of a Mermaid diagram + end: + - 'direction LR' ``` ## Determining config file location diff --git a/docs/generator_types.md b/docs/generator_types.md index 9d8de7ea..e52642ab 100644 --- a/docs/generator_types.md +++ b/docs/generator_types.md @@ -3,17 +3,19 @@ * [PlantUML](#plantuml) +* [MermaidJS](#mermaidjs) * [JSON](#json) -Currently, there are 2 types of diagram generators: `plantuml` and `json`. +Currently, there are 3 types of diagram generators: `plantuml`, `mermaid` +and `json`. To specify, which generators should be used on the command line use option `-g`. For instance to generate both types of diagrams run `clang-uml` as follows: ```bash -clang-uml -g plantuml -g json +clang-uml -g plantuml -g mermaid -g json ``` By default, only `plantuml` diagrams are generated. @@ -92,6 +94,70 @@ __ The footer at the end is added by default, but can be disabled with `--no-metadata` command line option. +## MermaidJS + +This generator, creates UML diagrams in textual MermaidJS format, which can then +be used directly in some Markdown renderers (e.g. GitHub) or converted to +various image formats using [mermaid-cli](https://github.com/mermaid-js/mermaid-cli). + +In case there is a need for adding custom MermaidJS directives to generated +diagrams, they can be included directly in the diagram configuration. For +example: + +```yaml + mermaid: + before: + - direction LR + after: + - 'note for {{ alias("inheritable_diagram_options") }} "Options common to all diagram types."' + - 'note for {{ alias("config") }} "General options not used by diagrams."' +``` + +will add before the diagram contents (right after diagram type, +e.g. `classDiagram`) diagram direction hint, and after each diagram contents +2 notes attached to elements. + +An example MermaidJS diagram is presented below: + +``` +classDiagram + class C_0001371951663534295727["A"] + class C_0001371951663534295727 { + +A() : [default] void + +A(int i) : void + +A(A &&) : [default] void + +A(const A &) : void + +A(T t) : void + +~A() : [default] void + +operator=(A && other) : A & + +operator=(A & other) : A & + +operator++() : A & + +auto_method() : int + +basic_method() : void + +const_method() : [const] void + +create_from_int(int i) : A$ + +default_int(int i = 12) : int + +default_string(int i, std::string s = "abc") : std::string + +double_int(const int i) : int + -private_method() : void + #protected_method() : void + +size() : [const,constexpr] std::size_t + +static_method() : int$ + +sum(const double a, const double b) : int + -a_ : int + +auto_member : const unsigned long + -b_ : int + -c_ : int + #compare : std::function<bool (const int)> + -private_member : int + #protected_member : int + +public_member : int + +static_const_int : const int + +static_int : int + } + click C_0001371951663534295727 href "https://github.com/bkryza/clang-uml/blob/70e70888231938ba5310a8e0e28b9351beba21ef/tests/t00003/t00003.cc#L7" "A" +``` + ## JSON Generates a JSON representation of the intermediate `clang-uml` model, which diff --git a/docs/img/mermaid_aggregation.png b/docs/img/mermaid_aggregation.png new file mode 100644 index 00000000..10a052b7 Binary files /dev/null and b/docs/img/mermaid_aggregation.png differ diff --git a/docs/img/mermaid_association.png b/docs/img/mermaid_association.png new file mode 100644 index 00000000..005737e6 Binary files /dev/null and b/docs/img/mermaid_association.png differ diff --git a/docs/img/mermaid_composition.png b/docs/img/mermaid_composition.png new file mode 100644 index 00000000..3562b65a Binary files /dev/null and b/docs/img/mermaid_composition.png differ diff --git a/docs/img/mermaid_dependency.png b/docs/img/mermaid_dependency.png new file mode 100644 index 00000000..f4cb8a9c Binary files /dev/null and b/docs/img/mermaid_dependency.png differ diff --git a/docs/img/mermaid_inheritance.png b/docs/img/mermaid_inheritance.png new file mode 100644 index 00000000..01b75c5f Binary files /dev/null and b/docs/img/mermaid_inheritance.png differ diff --git a/docs/img/mermaid_instantiation.png b/docs/img/mermaid_instantiation.png new file mode 100644 index 00000000..cde3a265 Binary files /dev/null and b/docs/img/mermaid_instantiation.png differ diff --git a/docs/img/mermaid_nested.png b/docs/img/mermaid_nested.png new file mode 100644 index 00000000..144c5c4f Binary files /dev/null and b/docs/img/mermaid_nested.png differ diff --git a/docs/interactive_svg_diagrams.md b/docs/interactive_svg_diagrams.md index d59de82b..aadb6375 100644 --- a/docs/interactive_svg_diagrams.md +++ b/docs/interactive_svg_diagrams.md @@ -6,12 +6,14 @@ -`clang-uml` in combination with PlantUML's link generation in diagrams allows to generate interactive diagrams, -where clicking on any class, method or call expression can direct the user directly to the source code or some other +`clang-uml` in combination with PlantUML's link generation in diagrams allows to +generate interactive diagrams, where clicking on any class, method or call +expression can direct the user directly to the source code or some other diagram or document available online. -For instance to generate links to GitHub repository directly for most of diagram elements simple add this to your -`.clang-uml` file: +For instance to generate links to GitHub repository directly for most diagram +elements simple add this to your `.clang-uml` file: + ```yaml generate_links: link: 'https://github.com/myorg/myrepo/blob/{{ git.commit }}/{{ element.source.path }}#L{{ element.source.line }}' diff --git a/docs/quick_start.md b/docs/quick_start.md index 254a836a..c687784e 100644 --- a/docs/quick_start.md +++ b/docs/quick_start.md @@ -44,8 +44,14 @@ To add an initial class diagram to your project, follow these steps: ``` 4. Generate SVG images from the PlantUML diagrams: ```bash - plantuml -tsvg puml/*.puml + plantuml -tsvg diagrams/*.puml ``` + or generate also MermaidJS diagram (requires [mermaid-cli](https://github.com/mermaid-js/mermaid-cli)): + ``` + clang-uml --progress -n some_class_diagram -g mermaid + mmdc -i diagrams/some_class_diagram.mmd -o diagrams/some_class_diagram.svg + ``` + 5. Add another diagram: ```bash clang-uml --add-sequence-diagram another_diagram