search

os6sense / xumlidot

RUBY UML class diagram generator with XMI and DOT output.
MIT License
40 stars 7 forks source link
class-diagram dot rails ruby uml uml-diagram xmi

readme

XUMLIDOT

A Ruby UML XMI and DOT diagram generator

VERSION 0.2.0 - Whats new?

WHAT DOES IT DO SO FAR?

WARNING

xumlidot will quite happily trundle away and create some simply massive xmi or dot files. When these are converted to an image, these will often get scaled down by graphviz and even if they don't, some image viewers stuggle with large svg/png images. Visual Paradigm can absolutely choke. Consider the --no-inheritance and --no-composition options to reduce the complexity/size, or just focusing in on specific directories to create smaller diagrams.

WHY?

This is a tool I made for myself (hence the long gaps between releases). I'm a fan of Model Driven Engineering and whilst there are great tools like Railroady and Xamin out there, the focus on Rails makes them less useful than I personally would like since Ruby != Rails. Also Railroady has never had a working XMI option meaning that we can't import the output into tools such as Visual Paradigm - one of my primary use cases (although being able to output wall spanning class diagrams is very cool).

In addition, one of the major problems (IMO) with the approach taken by other tools is that they require files, hence you need a project with all the dependencies set up and working; fine most of the time but I've come across more than one project so environment dependent that even the specs would not run without spooling up vagrant or if you're lucky docker.

I wanted a tool where I can quickly get a high level view of the code from an Object Oriented perspective. Hence xumlidot ...

INSTALLATION

gem install xumlidot

I've only been using xumlidot globally - it's probably perfectly possible to add to a projects Gemfile and bundle exec it, but I've not had cause to.

USAGE

xumlidot OPTIONS dir_a dir_b dir_c ...

xumlidot basically expects a list of directories from which it will create the DOT or XMI output. You can of course just point it at the root of a project but I've found it useful to exclude tests/specs, and in a rails project, you don't really want the migrations, so I tend to use something like xumlidot --xmi app lib for a more focused model.

USE CASES

Often I will come into a project and want a high level overview of things. My go to tool was Railroady but this is only of use for Rails projects - now I use xumlidot.

I found myself this week having performed a refactor on a piece of code, creating a common interface and splitting out classes to adhere to SRP. From there I wanted to add in some PoC error handling (combining retrys and circuit breakers). I was able to easiliy generate a diagram of the refactored code, import it into Visual Paradigm, and then use the model to explore the functionality I wanted to add. (Its always nice when you make a tool and then find it works!)

OPTIONS

--title Provides a title to use for the diagram

--model Provides a name for the model

--dot Output diagram using dot

--xmi Output diagram using xmi

--debug Output (possibly too much) debug info.

--exclude Exclude directories or filenames matching string or pattern

--no-inheritance Dont output inheritance links

--no-composition Dont output composition links

EXAMPLE

  xumlidot --xmi --title="Xumlidot Class Diagram" app lib > xmulidot.xmi

Should produce a reasonable complete class diagram for a rails project - you may need to do seperate diagrams for different areas if you hit some limits in e.g. VP.

Xumlidot inceptin itself

The above is a demonstration image produced from importing into VisualParadigm the xmi output of xumlidot graphing itself. In VisualParadigm I tweaked the box size so as to fit all the method_names, and set the layout to orthagonal, then exported to png.

MAKING THINGS PRETTY

The raw output is just text sent to stdout so Graphviz dot/VisualParadigm are needed for the pretty stuff.

On Ubuntu I tend to do something like:

xumlidot app lib | dot -Tsvg -o diagram.svg && xdg-open diagram.svg

Which creates a quick diagram to see the structure of a project.

Graphviz

Have a look at examples_output/README.md for a couple of examples using dot. dot is beyond the scope of documenting here do please look at https://graphviz.org/ for further info.

Visual Paradigm

I'm still playing with VP and hope to add some tips of how to obtain the best results at somepoint. Tweaking the box size so as to fit all the method_names, and setting the layout to your preference orthagonal seems to be all that is needed for a reasonable diagram; be warned however, things can be slow and there may be VP settings you need to tweak for large projects.

DEPENDENCIES

You will need graphviz installed in order to parse the dot output.

DEVELOPMENT PLAN/TODO

COPYRIGHTS/ATTTRIBUTIONS/THANKS