Murdoc — a ruby documenter

Murdoc is a doccu-style annotated documentation generator.

Rationale

Sometimes it makes sense to create a guide, a story told by code and comments side by side. Murdoc generates a pretty html for such a story.

Example

Demo at GH.pages.

See also:

Usage

Dependencies

License

Public domain, see UNLICENSE file.

See also

Murdoc is yet another Doccu-like documentation generator. Murdoc reads ruby source files and produces annotated html documentation.

See also: Docco, Rocco

  1. 12
module Murdoc

AnnotatedFile is a struct we pass into our templates

  1. 14
AnnotatedFile = Struct.new(:filename, :metadata, :source, :source_type, :paragraphs, :formatted_paragraphs)

Murdoc.annotate arguments are gathered from CLI utility

highlight regulates syntax highlighting and do_not_count_comment_lines flag toggles counting comment lines towards line numbering in the output.

  1. 20
  2. 21
  3. 22
  4. 23
  5. 24
  6. 25
  7. 26
  8. 27
  9. 28
  10. 29
def self.annotate(filename, highlight = true, do_not_count_comment_lines = false) filename = File.expand_path(filename) annotator = Annotator.from_file(filename, nil, do_not_count_comment_lines) AnnotatedFile.new(filename, annotator.metadata, annotator.source, annotator.source_type, annotator.paragraphs, annotator.paragraphs.map {|p| FormattedParagraph.new(p, highlight) }) end

Generate a single file story

  1. 32
  2. 33
  3. 34
  4. 35
  5. 36
  6. 37
  7. 38
  8. 39
  9. 40
def self.generate_from_file(input, output, options = {}) options = default_options.merge(options) annotator = Annotator.from_file(input, nil) File.open(output, "w+") do |f| annotated_file = annotate(input, options[:highlight], options[:do_not_count_comment_lines]) f.puts Renderer.new(options[:template]).render(:annotated_file => annotated_file, :stylesheet => File.read(options[:stylesheet])) end end

… or use multiple files

  1. 43
  2. 44
  3. 45
  4. 46
  5. 47
  6. 48
  7. 49
  8. 50
def self.generate_from_multiple_files(input_files, output, options = {}) options = default_options_for_multiple_files.merge(options) annotated_files = input_files.map {|fn| annotate(fn, options[:highlight], options[:do_not_count_comment_lines]) } File.open(output, "w+") do |f| f.puts Renderer.new(options[:template]).render(:annotated_files => annotated_files, :stylesheet => File.read(options[:stylesheet])) end end

Rest is self-explanatory

  1. 54
  2. 55
  3. 56
  4. 57
  5. 58
  6. 59
  7. 60
  8. 61
  9. 62
  10. 63
  11. 64
  12. 65
  13. 66
  14. 67
  15. 68
  16. 69
  17. 70
  18. 71
  19. 72
  20. 73
  21. 74
  22. 75
  23. 76
  24. 77
  25. 78
  26. 79
  27. 80
  28. 81
  29. 82
  30. 83
  31. 84
  32. 85
def self.default_options @options ||= { template: "#{markup_dir}/template.haml", stylesheet: "#{markup_dir}/stylesheet.css", highlight: true } end def self.default_options_for_multiple_files @options ||= { template: "#{markup_dir}/template_multifile.haml", stylesheet: "#{markup_dir}/stylesheet.css", highlight: true } end def self.markup_dir File.expand_path("../..", __FILE__)+ "/markup" end end require "murdoc/annotator" require "murdoc/scanner" require "murdoc/paragraph" require "murdoc/formatted_paragraph" require "murdoc/renderer" require "murdoc/languages/base" require "murdoc/languages/html" require "murdoc/languages/coffeescript" require "murdoc/languages/javascript" require "murdoc/languages/ruby" require "murdoc/languages/markdown"