-
Notifications
You must be signed in to change notification settings - Fork 66
add UML page #399
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: source
Are you sure you want to change the base?
add UML page #399
Changes from all commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
Suggested change
|
||||||
|
||||||
| Language | Tools | | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. This table is a little squished, so I'll make separate pr to update the bootstrap css and add some padding. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. |
||||||
| -------- | ----- | | ||||||
| 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
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. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. static state seems redundant.
Suggested change
|
||||||
UML diagram is below: | ||||||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. 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.
