Autogenerate a dash docset with object graph and documentation statistics on rails migrate

June 13, 2016

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

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:

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:


/documentation/images/graph.*
/documentation/TRANSFORMED-README.md
.yardoc
/doc

Documentation

Your documentation/README.md 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/graph.dot.png)

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

Dash

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.

Rake

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/graph.dot')
         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/graph.dot ')
         fail(SystemCallError, $CHILD_STATUS.to_s) unless result
      end
      desc 'Replaces the Placeholder in README.md with Documentation statistics.'
      task :stats do
         stats = '* ' + %x(yard stats).split("\n").join("\n *")
         IO.write(
            'documentation/TRANSFORMED-README.md',
            File.read('documentation/README.md').gsub(/~~~This is autreplaced by the rake task~~~\n~~~STATS~~~\n/, stats)
         )
      end
      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/TRANSFORMED-README.md
')
      end
      desc 'Generates dash docset from yard output'
      task dash: :yard do
         DocToDash::DocsetGenerator.new(doc_input_path: 'doc/yard', docset_name: 'My Docset', docset_output_path: 'doc/dash').run
      end
   end
   # 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
            Rake::Task['set_annotation_options'].invoke
            Annotate::Migration.update_annotations
            Rake::Task['doc:dash'].invoke
         end

   namespace cmd do
      %i(:change, :up, :down, :reset, :redo).each do |t|
         task t do
            Rake::Task['set_annotation_options'].invoke
            Annotate::Migration.update_annotations
            Rake::Task['doc:dash'].invoke
         end
      end
   end
end
Autogenerate a Dash Docset with Object Graph and documentation Statistics on Rails Migrate - June 13, 2016 - mw