add UML page #399
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,38 @@ | ||||||
| --- | ||||||
| layout: manual | ||||||
| title: Generating UML Diagrams | ||||||
| subtitle: "Generating UML Diagrams" | ||||||
| permalink: /manual/guides/uml | ||||||
| --- | ||||||
|
|
||||||
| Universal Modeling Language (UML) diagrams are a common way to visually | ||||||
| represent software components (such as classes and functions). When reviewing | ||||||
| code with someone new to the software, UML diagrams can be a useful tool. | ||||||
|
There was a problem hiding this comment. Sometimes these diagrams are automatically generated as part of the automated documentation (e.g. Doxygen). It may be worth mentioning that one can just check if that's the case for the software you're dealing with. (https://fuelcycle.org/cyclus/classcyclus_1_1Agent.html) |
||||||
|
|
||||||
| Rather than writing UML diagrams by hand, we can generate them from existing | ||||||
| code using existing software tools. T | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| | Language | Tools | | ||||||
|
There was a problem hiding this comment. This table is a little squished, so I'll make separate pr to update the bootstrap css and add some padding. |
||||||
| | -------- | ----- | | ||||||
| | C++ | [clang-uml](https://clang-uml.github.io/index.html) | | ||||||
| | Python | [pyreverse](https://pylint.pycqa.org/en/latest/additional_tools/pyreverse/index.html) | | ||||||
|
There was a problem hiding this comment. I think you should be able to just use the native "inheritance diagram" functionality inside sphinx (which is probably what folks are using for automated documentation anyway). Alternatively, if that's somehow not working and your tool already uses sphinx for documentation, there's a compatible tool called PlantUML. https://github.com/sphinx-contrib/plantuml |
||||||
|
|
||||||
| `clang-uml` uses `clang`, and as such requires the `compile_commands.json` file. | ||||||
| The creator of `clang-uml` wrote a [blog | ||||||
| post](https://blog.bkryza.com/posts/compile-commands-json-gallery/) blog post | ||||||
|
There was a problem hiding this comment.
Suggested change
|
||||||
| explaining how to generate `compile_commands.json` for various build systems). | ||||||
|
|
||||||
| `pyreverse` is included in (`pylint`)[https://www.pylint.org/]. `pyreverse` | ||||||
| relies on [`graphviz`](https://graphviz.org/) to generate the UML diagrams in | ||||||
| the DOT format. It is more limited than `clang-uml`, but there are limited | ||||||
| options outside of using an IDE. | ||||||
|
|
||||||
| The most common type of UML diagram is the _class diagram_. This represents the | ||||||
| static state of the code, including any inhertiance structures. An example of a | ||||||
|
There was a problem hiding this comment. static state seems redundant.
Suggested change
|
||||||
| UML diagram is below: | ||||||
|
There was a problem hiding this comment. I don't see any UML diagram example here. |
||||||
|
|
||||||
|
|
||||||
| It can be difficult to come up with a representation of program flow statically, | ||||||
| so as an alternative to UML diagrams, the tool | ||||||
| [`gprof2dot`](https://github.com/jrfonseca/gprof2dot?tab=readme-ov-file) uses a | ||||||
| profiler to track function calls and converts it into a graph. | ||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This is a little redundant.
