Class: DoubleDoc::Task

Inherits:
Object
  • Object
show all
Includes:
Rake::DSL
Defined in:
lib/double_doc/task.rb

Overview

### Rake Task It is very easy to set up a rake task for generating your documentation. All you have to do is tell DoubleDoc what the input files are, and where you want the output to go.

“‘ruby require ’double_doc’

DoubleDoc::Task.new(:doc,

:sources          => 'doc/source/*.md',
:md_destination   => 'doc/generated',
:html_destination => 'site'

) “‘

The available options are:

| name | Description | ——————– | ———– | __sources__ | __Required__. This tells Double doc where to look for the source of the documentation. Can be either a string or an array of strings. | md_destination | __Required__. This is the directory where you want the generated markdown files to go. | html_destination | If you want a pretty HTML version of your documentation, all you have to do is to say where you want it. | html_template | You can use your own custom ERB template for HTML rendering. Have a look in the one we ship with DoubleDoc for inspiration (templates/default.html.erb). | html_renderer | If you want full control of the HTML rendering you can use your own implementation. Defaults to ‘DoubleDoc::HtmlRenderer`. | html_css | You can use your own custom CSS document by specifying it’s path here. | __title__ | The title you want in the generated HTML. Defaults to “Documentation”.

If you just want to use double doc to generate your README.md for github, you should write your documentation in doc/README.md and put his in your Rakefile:

“‘ruby require ’double_doc’

DoubleDoc::Task.new(:doc, :sources => ‘doc/README.md’, :md_destination => ‘.’) “‘ Then all you have to do is to run `rake doc`, and you will have a `readme.md` in the root of your project.

If you have a gh-pages branch set up in your repository, you can event run ‘rake doc:publish` to generate html documentation and push it to your github pages.

Instance Method Summary collapse

Constructor Details

#initialize(task_name, options) ⇒ Task

Returns a new instance of Task.



48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
 
# File 'lib/double_doc/task.rb', line 48

def initialize(task_name, options)
  md_dst   = Pathname.new(options[:md_destination])
  html_dst = Pathname.new(options[:html_destination]) if options[:html_destination]
  sources  = FileList[*options[:sources]].uniq

  destinations = [md_dst, html_dst].compact
  destinations.each do |dst|
    directory(dst.to_s)
  end

  desc "Generate markdown #{html_dst ? 'and HTML ' : ''}DoubleDoc documentation from #{sources.join(', ')}"
  generated_task = task(task_name => destinations) do |t, args|
    import_handler = DoubleDoc::ImportHandler.new(options[:root] || Rake.original_dir)

    generated_md_files = []

    sources.each do |src|
      dst = md_dst + File.basename(src)
      puts "#{src} -> #{dst}"
      File.open(dst, 'w') do |out|
        out.write(import_handler.resolve_imports(File.new(src)))
      end
      generated_md_files << dst
    end

    if html_dst || args[:html_destination]
      html_generator = DoubleDoc::HtmlGenerator.new(generated_md_files, options.merge(args))
      html_generator.generate
    end

  end

  has_github_pages = !`git branch | grep 'gh-pages'`.empty? rescue false

  if has_github_pages
    namespace(task_name) do
      desc "Publish DoubleDoc documentation to Github Pages"
      task :publish do
        git_clean = `git status -s`.empty? rescue false
        raise "Your local git repository needs to be clean for this task to run" unless git_clean

        git_branch = `git branch | grep "*"`.match(/\* (.*)/)[1] rescue 'master'

        Dir.mktmpdir do |dir|
          generated_task.execute(:html_destination => dir)
          html_files = Dir.glob(Pathname.new(dir) + '*.html')

          `git add .`
          `git commit -n -m 'Updated documentation'`
          `git checkout gh-pages`
          `git pull origin gh-pages`
          `cp #{dir}/* .`
          if html_files.size == 1
            `cp #{html_files[0]} index.html`
          else
            warn("You should probably generate an index.html")
          end
          `git add .`
          `git commit -n -m 'Updated Github Pages'`
          `git push origin gh-pages`
          `git co #{git_branch}`
        end
      end
    end
  end
end