Autogenerate a Dash Docset with Object Graph and documentation Statistics on Rails Migrate

Jun 13, 2016

These are a few rake tasks that automate my current rails documentation workflow. Specifically, they add:

  • Generating the Object Graph as a dotfile and rendering it with Graphviz
  • Adding a short overview of Documentation Statistics to the documentation index.
  • Generating a docset for Dash from the Yard documentation.

Auto-annotation of Models

This uses the Annotate Models gem. Install the gem as well as the Kramdown gem, run rails g annotate:install and edit the options in lib/tasks/auto_annotate_models.rake to:

  • ```format_markdown’: true

Object Graph

Yard can generate a simple overview of your Model structure as a dotfile. You’ll need graphviz to render it to a png – install it with, i. e. brew install graphviz.

Ignorance is bliss

You will want to add the automatically generated files to .gitignore:



Your documentation/ should include the Object Graph and a placeholder for statistics – it appears that kramdown cannot include a separat markdown file:

# My Documentation

![Object Graph](images/

## Code Statistics
~~~This is autreplaced by the rake task~~~


Running rake doc:dash should generate a Dash Docset in doc/dash. Double-Clicking should add it to Dash. You can hit CMD+R to refresh.


And this is, for example, documentation.rake:

# frozen_string_literal: true
# Let's make sure this doesn't happen in production
if Rails.env.development?
   namespace :doc do
      desc 'Generates the graph of Model Dependencies as a dotfile and renders it with Graphviz.'
      task :graph do
         result = Kernel.system('yard graph > documentation/images/')
         fail(SystemCallError, $CHILD_STATUS.to_s) unless result
         # -x "reduces the Graph", which sounds like a good idea
         # The Size is set to 11 inches width, after which it should grow down
         # if the ratio=compress does what I hope it does
         result = Kernel.system('dot -Tpng -O -x -Gratio=compress -Gsize=11,200 documentation/images/ ')
         fail(SystemCallError, $CHILD_STATUS.to_s) unless result
      desc 'Replaces the Placeholder in with Documentation statistics.'
      task :stats do
         stats = '* ' + %x(yard stats).split("\n").join("\n *")
  'documentation/').gsub(/~~~This is autreplaced by the rake task~~~\n~~~STATS~~~\n/, stats)
      desc 'Runs yard documentation generator.'
      task yard: [:stats, :graph] do
         Kernel.exec('yard doc --markup markdown --markup-provider kramdown --asset documentation/images:images --output-dir doc/yard --readme documentation/
      desc 'Generates dash docset from yard output'
      task dash: :yard do 'doc/yard', docset_name: 'My Docset', docset_output_path: 'doc/dash').run
   # Adds our documentation tasks to db:migrate:*. We only need doc:dash
   # as the others are dependencies
   namespace :db do
      %i(:migrate, :rollback).each do |cmd|
         task cmd do

   namespace cmd do
      %i(:change, :up, :down, :reset, :redo).each do |t|
         task t do

Other Articles

Mark Felt-Tipped Feb 25, 2018

Building Tensorflow 1.5.0 on MacOS with CUDA GPU Jan 21, 2018

Contact Jan 1, 2018

iTunes crashes with MediaControlSender AVSystemController_GetAirPlayInfo Aug 18, 2017

Add iterm2 marks to long-running outputs Jun 1, 2017

Trump Documents Atbash Decoded May 23, 2017

Polkit? WTF is this again? Actually... May 23, 2017

osacompile: no such component "JavaScript" May 2, 2017

" glxQueryVersion failed" with a headless chrome on alpine Mar 17, 2017

lighthouse/chromium/alpine/docker image Mar 9, 2017

Don't know how to build task '# Mar 6, 2017

sfdp: Error: Graphviz not built with triangulation library Jan 7, 2017

link_directory must be a directory Jan 2, 2017

Deactivating the Z170N's internal bluetooth in Clover Jul 3, 2016

Autogenerate a Dash Docset with Object Graph and documentation Statistics on Rails Migrate Jun 13, 2016

Massdrop is the worst spammer I've seen since the 90ies May 23, 2016

Verifying NGINX configurations in ansible May 23, 2016

ANSIBLE-MODULE-PATH and more Apr 29, 2016

'' is not a git command Apr 23, 2016

I rule (.svg) Mar 8, 2016

React and Relay error scrapbook Mar 3, 2016

Get a Grid, at least vertically Feb 17, 2016

Uncaught TypeError: Iterator value meps is not an entry object Nov 14, 2015

Controlled Jekyll Republishing with git Commit Messages Nov 2, 2015