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
- ```format_markdown’: true
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
/documentation/images/graph.* /documentation/TRANSFORMED-README.md .yardoc /doc
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~~~
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,
# 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
Mark Felt-Tipped Feb 25, 2018
Building Tensorflow 1.5.0 on MacOS with CUDA GPU Jan 21, 2018
Contact Jan 1, 2018
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
lighthouse/chromium/alpine/docker image Mar 9, 2017
Don't know how to build task '#
link_directory must be a directory Jan 2, 2017
Verifying NGINX configurations in ansible May 23, 2016
ANSIBLE-MODULE-PATH and more Apr 29, 2016
'credentials-gcloud.sh' 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