add UML page #399
add UML page #399
Conversation
| code with someone new to the software, UML diagrams can be a useful tool. | ||
|
|
||
| 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.
| code using existing software tools. T | |
| code using existing software tools. |
|
|
||
| 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)
|
|
||
| `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.
| post](https://blog.bkryza.com/posts/compile-commands-json-gallery/) blog post | |
| post](https://blog.bkryza.com/posts/compile-commands-json-gallery/) |
| | Language | Tools | | ||
| | -------- | ----- | | ||
| | 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
| 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.
| static state of the code, including any inhertiance structures. An example of a | |
| state of the code, including any inheritance structures. An example of a |
|
|
||
| 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 | ||
| UML diagram is below: |
There was a problem hiding this comment.
I don't see any UML diagram example here.
| Rather than writing UML diagrams by hand, we can generate them from existing | ||
| code using existing software tools. T | ||
|
|
||
| | 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.
|
Sorry I jumped the gun. Just realized this was a draft PR. |
| title: Generating UML Diagrams | ||
| subtitle: "Generating UML Diagrams" |
There was a problem hiding this comment.
This is a little redundant.
| title: Generating UML Diagrams | |
| subtitle: "Generating UML Diagrams" | |
| title: Inheritance Diagrams | |
| subtitle: "Generating Inheritance Diagrams with UML" |
|
@yardasol -- pinging. |
Summary of changes
This PR adds a page describing UML diagrams and points to some tools for generating them.
Types of changes
Associated Issues and PRs
Associated Developers
Checklist for Reviewers
Reviewers should use this link to get to the
Review Checklist before they begin their review.