Graphviz Config

Overview

Graphviz is a very mature and customisable diagram generation tool. See here for the official docs, or here for an unofficial online playground.

You'll need to install Graphviz's binary executables separately, to use them as part of Atlas, see here for steps.

Config is done with the graphviz lambda block within the base atlas extension:

plugins {
  id("dev.jonpoulton.atlas.graphviz") version "x.y.z"
}

atlas {
  // other Atlas config - see common config docs

  graphviz {
    pathToDotCommand = "/path/to/dot"
    fileFormat = FileFormat.Svg
    layoutEngine = LayoutEngine.Dot

    node {
      // ...
    }

    edge {
      // ...
    }

    graph {
      // ...
    }
  }
}

Generated Files

Atlas Graphviz will generate a chart.dot file in each project directory, plus an image file based on your choice of fileFormat. In the root project it'll also generate a legend.dot and an accompanying image. Both of these will be auto-added to the project readme when either gradle atlasGenerate or gradle writeGraphvizReadme is run.

Properties

pathToDotCommand

atlas {
  graphviz {
    pathToDotCommand = "/path/to/dot"
  }
}

By default, Atlas will try to call dot from the system PATH. Use this to specify from a custom installation location instead.

fileFormat

atlas {
  graphviz {
    fileFormat = FileFormat.Svg
  }
}

There are plenty of options here, all those specified in the Graphviz docs are provided as options by Atlas in the FileFormat enum. Not all have been tested, so please raise an issue on Github if you see anything weird.

layoutEngine

atlas {
  graphviz {
    layoutEngine = LayoutEngine.Dot
  }
}

DOT is Graphviz's standard engine, but others are available too. See the docs here. In my experience the only ones to give decent layouts for charts like these are:

• dot
• circo
• neato

though some of them (cough neato cough) will probably need tweaking of properties to make them look decent. Try experimenting to see what fits best.

Functions

As mentioned in the Extra Properties section on the previous page, the following three config sections all implement PropertiesSpec. As such, you can call put("key", value) within each of these lambda blocks to pass in your own config options - in case you want to set a property which hasn't been exposed by Atlas yet.

node

Set a bunch of properties to be applied to all project nodes - unless overridden by projectTypes config. Some examples below, though you'll want to go through the Graphviz docs for all restrictions/requirements:

atlas {
  graphviz {
    node {
      fillColor = "red"
      fontColor = "white"
      shape = Shape.Box
      style = NodeStyle.Solid
    }
  }
}

atlas {
  projectTypes {
    hasPluginId("Custom", "com.custom.plugin") {
      // overrides fill/shape for this project type only
      fillColor = "#ABC123"
      shape = Shape.Star
    }
  }

  node {
    // all others are red eggs by default
    fillColor = "red"
    shape = Shape.Egg
  }
}

There's plenty you can do here, not all of it is immediately easy to figure out at a glance. Blame Graphviz, not me - this is simply a pass-through config layer. All node-specific properties - along with their types and associated Graphviz docs - are listed below. All properties are unset by default.

edge

Set a bunch of properties to be applied to all links between project nodes - unless overridden by linkTypes config. Some examples below, though you'll want to go through the Graphviz docs for all restrictions/requirements:

atlas {
  graphviz {
    edge {
      linkColor = "red"
      fontColor = "white"
      arrowHead = ArrowType.Box
      weight = 2
    }
  }
}

There's plenty you can do here, not all of it is immediately easy to figure out at a glance. Blame Graphviz, not me - this is simply a pass-through config layer. All link-specific properties - along with their types and associated Graphviz docs - are listed below. All properties are unset by default.

atlas {
  linkTypes {
    api {
      // overrides arrow/color for this link type only
      arrowHead = ArrowType.Diamond
      linkColor = "red"
    }

    implementation()
  }

  edge {
    // all others are black boxes by default
    arrowHead = ArrowType.Box
    linkColor = "black"
  }
}

graph

Set a bunch of properties to be applied to the chart itself. Some examples below, though you'll want to go through the Graphviz docs for all restrictions/requirements:

atlas {
  graphviz {
    graph {
      bgColor = "black"
      fontColor = "white"
      labelLoc = "b"
    }
  }
}