Need to write a README file, but not sure what to say? If this is a frustration that bothers you frequently, you might consider beefing your document up with a diagram. After all, a picture is worth a thousand words, as the cliche goes.
This article collects tools that generates graphs for a code repository.
Visualize files by size and type
Let’s start with the most generic tool,
repo-visualizer. It plots files as bubbles, indicating their extension names and sizes with colors and sizes, respectively. It's brought to you by GitHub Next, a lab at GitHub the company, and (naturally) it's packaged as a GitHub Action.
Visualize Docker Compose files
The next tool specifically caters to Docker users, but it’s still language-agnostic. To visualize
docker-compose.yml, you can use
docker run \--rm \-it \--name dcv \-v $(pwd):/input pmsipilot/docker-compose-viz render \-m image docker-compose.yml
Here’s how it would look:
I like how it’s also plotting extra information like open ports and mounted volumes.
Visualize call graphs
Here’s the example provided in its README:
code2flow code2flow/engine.py code2flow/python.py --target-function=code2flow --downstream-depth=3
If Python is the only language you care about, you might have heard of
pycallgraph , but -- alas, the bane of open source software projects -- the original author had to abandon the project due to personal time constraints. The most sensible alternative I can find is
pyan *.py --uses --no-defines --colored --grouped --annotated --svg >myuses.svg
A fundamental functionality of build systems and package managers is dependency resolution. As you’d expect, many visualization tools tap into dependency graphs generated by these software to plot diagrams for a repository.
Under the hood, most of these tools use
graphviz for the actual plotting work. Therefore, don't be surprised to discover that the diagrams share a similar style.
Bazel is a language-agnostic build system. The developers behind Bazel know its users so well that they put up an official guide for visualizing dependencies defined with Bazel:
bazel query 'deps(//:main)' --output graph > dependencies.in
dot -Tpng < dependencies.in > dependencies.svg
It gives something like this:
For Python packages in an environment, use
pipdeptree --graph-output svg > dependencies.svg
For Java projects built with Maven,
depgraph-maven-plugin is the way to go:
I want more interactivity!
Maybe you’re not here to fill up your README; rather, you just want to learn about a repo as quickly and intuitively as possible. If that’s the case, there are some nice tools you can play with:
I’m not endorsing either of them, and they are beyond the scope of this post. Nevertheless, this serves as a good point to wrap up this post. Writing an ending is painful, and I’m sure you’re aware of that — Otherwise, you would not have landed on this very article that helps you evade the chore of composing words, would you?