Skip to content

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

Draft
wants to merge 1 commit into
base: source
Choose a base branch
from
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions manual/guides/guides.md
Original file line number Diff line number Diff line change
Expand Up @@ -114,6 +114,7 @@ twitter accounts, and whatnot that tie us together.
- Cloud Computing
- [Using Blue Waters](/manual/guides/bluewaters)
- [Using Git Large File Storage](/manual/guides/git-lfs)
- [Generating UML diagrams](/manual/guides/uml)


# Presenting Work
Expand Down
38 changes: 38 additions & 0 deletions manual/guides/uml.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
---
layout: manual
title: Generating UML Diagrams
subtitle: "Generating UML Diagrams"
Comment on lines +3 to +4
Copy link
Member

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.
image

Suggested change
title: Generating UML Diagrams
subtitle: "Generating UML Diagrams"
title: Inheritance Diagrams
subtitle: "Generating Inheritance Diagrams with UML"

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.
Copy link
Member

Choose a reason for hiding this comment

The 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
code using existing software tools. T
code using existing software tools.


| Language | Tools |
Copy link
Member

Choose a reason for hiding this comment

The 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.

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image

| -------- | ----- |
| C++ | [clang-uml](https://clang-uml.github.io/index.html) |
| Python | [pyreverse](https://pylint.pycqa.org/en/latest/additional_tools/pyreverse/index.html) |
Copy link
Member

Choose a reason for hiding this comment

The 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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
post](https://blog.bkryza.com/posts/compile-commands-json-gallery/) blog post
post](https://blog.bkryza.com/posts/compile-commands-json-gallery/)

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

static state seems redundant.

Suggested change
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

UML diagram is below:
Copy link
Member

Choose a reason for hiding this comment

The 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.