2010-03-11 11:25:35 +00:00
|
|
|
<!DOCTYPE html>
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<meta http-equiv="content-type" content="text/html;charset=utf-8">
|
|
|
|
|
<title>tasks.rb</title>
|
|
|
|
|
<link rel="stylesheet" href="http://jashkenas.github.com/docco/resources/docco.css">
|
|
|
|
|
</head>
|
|
|
|
|
<body>
|
|
|
|
|
<div id='container'>
|
|
|
|
|
<div id="background"></div>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div id="jump_to">
|
|
|
|
|
Jump To …
|
|
|
|
|
<div id="jump_wrapper">
|
|
|
|
|
<div id="jump_page">
|
|
|
|
|
<a class="source" href="rocco.html">rocco.rb</a>
|
|
|
|
|
<a class="source" href="layout.html">layout.rb</a>
|
|
|
|
|
<a class="source" href="tasks.html">tasks.rb</a>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
|
|
|
|
</div>
|
2010-03-11 11:25:35 +00:00
|
|
|
<table cellspacing=0 cellpadding=0>
|
|
|
|
|
<thead>
|
|
|
|
|
<tr>
|
|
|
|
|
<th class=docs><h1>tasks.rb</h1></th>
|
|
|
|
|
<th class=code></th>
|
|
|
|
|
</tr>
|
|
|
|
|
</thead>
|
|
|
|
|
<tbody>
|
|
|
|
|
<tr id='section-1'>
|
|
|
|
|
<td class=docs>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div class="pilwrap">
|
|
|
|
|
<a class="pilcrow" href="#section-1">¶</a>
|
2010-03-11 11:25:35 +00:00
|
|
|
</div>
|
|
|
|
|
<h3>Rocco Rake Tasks</h3>
|
|
|
|
|
|
|
|
|
|
<p>To use the Rocco Rake tasks, require <code>rocco/tasks</code> in your <code>Rakefile</code>
|
|
|
|
|
and define a Rake task with <code>rocco_task</code>. In its simplest form, <code>rocco_task</code>
|
|
|
|
|
takes the path to a destination directory where HTML docs should be built:</p>
|
|
|
|
|
|
|
|
|
|
<pre><code>require 'rocco/tasks'
|
|
|
|
|
|
|
|
|
|
desc "Build Rocco Docs"
|
|
|
|
|
Rocco::make 'docs/'
|
|
|
|
|
</code></pre>
|
|
|
|
|
|
|
|
|
|
<p>This creates a <code>:rocco</code> rake task, which can then be run with:</p>
|
|
|
|
|
|
|
|
|
|
<pre><code>rake rocco
|
|
|
|
|
</code></pre>
|
|
|
|
|
|
|
|
|
|
<p>It’s a good idea to guard against Rocco not being available, since your
|
|
|
|
|
Rakefile will fail to load otherwise. Consider doing something like this,
|
|
|
|
|
so that your Rakefile will still work</p>
|
|
|
|
|
|
|
|
|
|
<pre><code>begin
|
|
|
|
|
require 'rocco/tasks'
|
|
|
|
|
Rocco::make 'docs/'
|
|
|
|
|
rescue LoadError
|
|
|
|
|
warn "#$! -- rocco tasks not loaded."
|
|
|
|
|
task :rocco
|
|
|
|
|
end
|
|
|
|
|
</code></pre>
|
|
|
|
|
|
|
|
|
|
<p>It’s also possible to pass a glob pattern:</p>
|
|
|
|
|
|
|
|
|
|
<pre><code>Rocco::make 'html/', 'lib/thing/**/*.rb'
|
|
|
|
|
</code></pre>
|
|
|
|
|
|
|
|
|
|
<p>Or a list of glob patterns:</p>
|
|
|
|
|
|
|
|
|
|
<pre><code>Rocco::make 'html/', ['lib/thing.rb', 'lib/thing/*.rb']
|
|
|
|
|
</code></pre>
|
2011-03-05 12:55:05 +00:00
|
|
|
|
|
|
|
|
<p>Finally, it is also possible to specify which Pygments language you would
|
|
|
|
|
like to use to highlight the code, as well as the comment characters for the
|
|
|
|
|
language in the <code>options</code> hash:</p>
|
|
|
|
|
|
|
|
|
|
<p> Rocco::make ‘html/’, ‘lib/thing/<em>*/</em>.rb’, {</p>
|
|
|
|
|
|
|
|
|
|
<pre><code> :language => 'io',
|
|
|
|
|
:comment_chars => '#'
|
|
|
|
|
</code></pre>
|
|
|
|
|
|
|
|
|
|
<p> }</p>
|
2010-03-11 11:25:35 +00:00
|
|
|
</td>
|
|
|
|
|
<td class=code>
|
|
|
|
|
<div class='highlight'><pre></pre></div>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr id='section-2'>
|
|
|
|
|
<td class=docs>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div class="pilwrap">
|
|
|
|
|
<a class="pilcrow" href="#section-2">¶</a>
|
2010-03-11 11:25:35 +00:00
|
|
|
</div>
|
|
|
|
|
<p>Might be nice to defer this until we actually need to build docs but this
|
|
|
|
|
will have to do for now.</p>
|
|
|
|
|
</td>
|
|
|
|
|
<td class=code>
|
|
|
|
|
<div class='highlight'><pre><span class="nb">require</span> <span class="s1">'rocco'</span></pre></div>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr id='section-3'>
|
|
|
|
|
<td class=docs>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div class="pilwrap">
|
|
|
|
|
<a class="pilcrow" href="#section-3">¶</a>
|
2010-03-11 11:25:35 +00:00
|
|
|
</div>
|
|
|
|
|
<p>Reopen the Rocco class and add a <code>make</code> class method. This is a simple bit
|
|
|
|
|
of sugar over <code>Rocco::Task.new</code>. If you want your Rake task to be named
|
|
|
|
|
something other than <code>:rocco</code>, you can use <code>Rocco::Task</code> directly.</p>
|
|
|
|
|
</td>
|
|
|
|
|
<td class=code>
|
|
|
|
|
<div class='highlight'><pre><span class="k">class</span> <span class="nc">Rocco</span>
|
2011-03-05 12:55:05 +00:00
|
|
|
<span class="k">def</span> <span class="nc">self</span><span class="o">.</span><span class="nf">make</span><span class="p">(</span><span class="n">dest</span><span class="o">=</span><span class="s1">'docs/'</span><span class="p">,</span> <span class="n">source_files</span><span class="o">=</span><span class="s1">'lib/**/*.rb'</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="p">{})</span>
|
|
|
|
|
<span class="no">Task</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="ss">:rocco</span><span class="p">,</span> <span class="n">dest</span><span class="p">,</span> <span class="n">source_files</span><span class="p">,</span> <span class="n">options</span><span class="p">)</span>
|
2010-03-11 11:25:35 +00:00
|
|
|
<span class="k">end</span></pre></div>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr id='section-4'>
|
|
|
|
|
<td class=docs>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div class="pilwrap">
|
|
|
|
|
<a class="pilcrow" href="#section-4">¶</a>
|
2010-03-11 11:25:35 +00:00
|
|
|
</div>
|
|
|
|
|
<p><code>Rocco::Task.new</code> takes a task name, the destination directory docs
|
|
|
|
|
should be built under, and a source file pattern or file list.</p>
|
|
|
|
|
</td>
|
|
|
|
|
<td class=code>
|
|
|
|
|
<div class='highlight'><pre> <span class="k">class</span> <span class="nc">Task</span>
|
2011-03-05 12:55:05 +00:00
|
|
|
<span class="k">def</span> <span class="nf">initialize</span><span class="p">(</span><span class="n">task_name</span><span class="p">,</span> <span class="n">dest</span><span class="o">=</span><span class="s1">'docs/'</span><span class="p">,</span> <span class="n">sources</span><span class="o">=</span><span class="s1">'lib/**/*.rb'</span><span class="p">,</span> <span class="n">options</span><span class="o">=</span><span class="p">{})</span>
|
2010-03-11 11:25:35 +00:00
|
|
|
<span class="vi">@name</span> <span class="o">=</span> <span class="n">task_name</span>
|
|
|
|
|
<span class="vi">@dest</span> <span class="o">=</span> <span class="n">dest</span><span class="o">[-</span><span class="mi">1</span><span class="o">]</span> <span class="o">==</span> <span class="sc">?/</span> <span class="p">?</span> <span class="n">dest</span> <span class="p">:</span> <span class="s2">"</span><span class="si">#{</span><span class="n">dest</span><span class="si">}</span><span class="s2">/"</span>
|
2011-03-05 12:55:05 +00:00
|
|
|
<span class="vi">@sources</span> <span class="o">=</span> <span class="no">FileList</span><span class="o">[</span><span class="n">sources</span><span class="o">]</span>
|
|
|
|
|
<span class="vi">@options</span> <span class="o">=</span> <span class="n">options</span></pre></div>
|
2010-03-11 11:25:35 +00:00
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr id='section-5'>
|
|
|
|
|
<td class=docs>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div class="pilwrap">
|
|
|
|
|
<a class="pilcrow" href="#section-5">¶</a>
|
2010-03-11 11:25:35 +00:00
|
|
|
</div>
|
|
|
|
|
<p>Make sure there’s a <code>directory</code> task defined for our destination.</p>
|
|
|
|
|
</td>
|
|
|
|
|
<td class=code>
|
|
|
|
|
<div class='highlight'><pre> <span class="n">define_directory_task</span> <span class="vi">@dest</span></pre></div>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr id='section-6'>
|
|
|
|
|
<td class=docs>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div class="pilwrap">
|
|
|
|
|
<a class="pilcrow" href="#section-6">¶</a>
|
2010-03-11 11:25:35 +00:00
|
|
|
</div>
|
|
|
|
|
<p>Run over the source file list, constructing destination filenames
|
|
|
|
|
and defining file tasks.</p>
|
|
|
|
|
</td>
|
|
|
|
|
<td class=code>
|
|
|
|
|
<div class='highlight'><pre> <span class="vi">@sources</span><span class="o">.</span><span class="n">each</span> <span class="k">do</span> <span class="o">|</span><span class="n">source_file</span><span class="o">|</span>
|
2011-03-05 12:55:05 +00:00
|
|
|
<span class="n">dest_file</span> <span class="o">=</span> <span class="no">File</span><span class="o">.</span><span class="n">basename</span><span class="p">(</span><span class="n">source_file</span><span class="p">)</span><span class="o">.</span><span class="n">split</span><span class="p">(</span><span class="s1">'.'</span><span class="p">)</span><span class="o">[</span><span class="mi">0</span><span class="o">.</span><span class="n">.</span><span class="o">-</span><span class="mi">2</span><span class="o">].</span><span class="n">join</span><span class="p">(</span><span class="s1">'.'</span><span class="p">)</span> <span class="o">+</span> <span class="s1">'.html'</span>
|
2010-03-11 11:25:35 +00:00
|
|
|
<span class="n">define_file_task</span> <span class="n">source_file</span><span class="p">,</span> <span class="s2">"</span><span class="si">#{</span><span class="vi">@dest</span><span class="si">}#{</span><span class="n">dest_file</span><span class="si">}</span><span class="s2">"</span></pre></div>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr id='section-7'>
|
|
|
|
|
<td class=docs>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div class="pilwrap">
|
|
|
|
|
<a class="pilcrow" href="#section-7">¶</a>
|
2010-03-11 11:25:35 +00:00
|
|
|
</div>
|
|
|
|
|
<p>If <code>rake/clean</code> was required, add the generated files to the list.
|
|
|
|
|
That way all Rocco generated are removed when running <code>rake clean</code>.</p>
|
|
|
|
|
</td>
|
|
|
|
|
<td class=code>
|
|
|
|
|
<div class='highlight'><pre> <span class="no">CLEAN</span><span class="o">.</span><span class="n">include</span> <span class="s2">"</span><span class="si">#{</span><span class="vi">@dest</span><span class="si">}#{</span><span class="n">dest_file</span><span class="si">}</span><span class="s2">"</span> <span class="k">if</span> <span class="n">defined?</span> <span class="no">CLEAN</span>
|
|
|
|
|
<span class="k">end</span>
|
|
|
|
|
<span class="k">end</span></pre></div>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr id='section-8'>
|
|
|
|
|
<td class=docs>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div class="pilwrap">
|
|
|
|
|
<a class="pilcrow" href="#section-8">¶</a>
|
2010-03-11 11:25:35 +00:00
|
|
|
</div>
|
|
|
|
|
<p>Define the destination directory task and make the <code>:rocco</code> task depend
|
|
|
|
|
on it. This causes the destination directory to be created if it doesn’t
|
|
|
|
|
already exist.</p>
|
|
|
|
|
</td>
|
|
|
|
|
<td class=code>
|
|
|
|
|
<div class='highlight'><pre> <span class="k">def</span> <span class="nf">define_directory_task</span><span class="p">(</span><span class="n">path</span><span class="p">)</span>
|
|
|
|
|
<span class="n">directory</span> <span class="n">path</span>
|
|
|
|
|
<span class="n">task</span> <span class="vi">@name</span> <span class="o">=></span> <span class="n">path</span>
|
|
|
|
|
<span class="k">end</span></pre></div>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr id='section-9'>
|
|
|
|
|
<td class=docs>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div class="pilwrap">
|
|
|
|
|
<a class="pilcrow" href="#section-9">¶</a>
|
2010-03-11 11:25:35 +00:00
|
|
|
</div>
|
|
|
|
|
<p>Setup a <code>file</code> task for a single Rocco output file (<code>dest_file</code>). It
|
|
|
|
|
depends on the source file, the destination directory, and all of Rocco’s
|
|
|
|
|
internal source code, so that the destination file is rebuilt when any of
|
|
|
|
|
those changes.</p>
|
|
|
|
|
|
|
|
|
|
<p>You can run these tasks directly with Rake:</p>
|
|
|
|
|
|
|
|
|
|
<pre><code>rake docs/foo.html docs/bar.html
|
|
|
|
|
</code></pre>
|
|
|
|
|
|
|
|
|
|
<p>… would generate the <code>foo.html</code> and <code>bar.html</code> files but only if they
|
|
|
|
|
don’t already exist or one of their dependencies was changed.</p>
|
|
|
|
|
</td>
|
|
|
|
|
<td class=code>
|
|
|
|
|
<div class='highlight'><pre> <span class="k">def</span> <span class="nf">define_file_task</span><span class="p">(</span><span class="n">source_file</span><span class="p">,</span> <span class="n">dest_file</span><span class="p">)</span>
|
|
|
|
|
<span class="n">prerequisites</span> <span class="o">=</span> <span class="o">[</span><span class="vi">@dest</span><span class="p">,</span> <span class="n">source_file</span><span class="o">]</span> <span class="o">+</span> <span class="n">rocco_source_files</span>
|
|
|
|
|
<span class="n">file</span> <span class="n">dest_file</span> <span class="o">=></span> <span class="n">prerequisites</span> <span class="k">do</span> <span class="o">|</span><span class="n">f</span><span class="o">|</span>
|
|
|
|
|
<span class="n">verbose</span> <span class="p">{</span> <span class="nb">puts</span> <span class="s2">"rocco: </span><span class="si">#{</span><span class="n">source_file</span><span class="si">}</span><span class="s2"> -> </span><span class="si">#{</span><span class="n">dest_file</span><span class="si">}</span><span class="s2">"</span> <span class="p">}</span>
|
2011-03-05 12:55:05 +00:00
|
|
|
<span class="n">rocco</span> <span class="o">=</span> <span class="no">Rocco</span><span class="o">.</span><span class="n">new</span><span class="p">(</span><span class="n">source_file</span><span class="p">,</span> <span class="vi">@sources</span><span class="o">.</span><span class="n">to_a</span><span class="p">,</span> <span class="vi">@options</span><span class="p">)</span>
|
2010-03-11 11:25:35 +00:00
|
|
|
<span class="no">File</span><span class="o">.</span><span class="n">open</span><span class="p">(</span><span class="n">dest_file</span><span class="p">,</span> <span class="s1">'wb'</span><span class="p">)</span> <span class="p">{</span> <span class="o">|</span><span class="n">fd</span><span class="o">|</span> <span class="n">fd</span><span class="o">.</span><span class="n">write</span><span class="p">(</span><span class="n">rocco</span><span class="o">.</span><span class="n">to_html</span><span class="p">)</span> <span class="p">}</span>
|
|
|
|
|
<span class="k">end</span>
|
|
|
|
|
<span class="n">task</span> <span class="vi">@name</span> <span class="o">=></span> <span class="n">dest_file</span>
|
|
|
|
|
<span class="k">end</span></pre></div>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr id='section-10'>
|
|
|
|
|
<td class=docs>
|
2011-03-05 12:55:05 +00:00
|
|
|
<div class="pilwrap">
|
|
|
|
|
<a class="pilcrow" href="#section-10">¶</a>
|
2010-03-11 11:25:35 +00:00
|
|
|
</div>
|
|
|
|
|
<p>Return a <code>FileList</code> that includes all of Roccos source files. This causes
|
|
|
|
|
output files to be regenerated properly when someone upgrades the Rocco
|
|
|
|
|
library.</p>
|
|
|
|
|
|
|
|
|
|
</td>
|
|
|
|
|
<td class=code>
|
|
|
|
|
<div class='highlight'><pre> <span class="k">def</span> <span class="nf">rocco_source_files</span>
|
|
|
|
|
<span class="n">libdir</span> <span class="o">=</span> <span class="no">File</span><span class="o">.</span><span class="n">expand_path</span><span class="p">(</span><span class="s1">'../..'</span><span class="p">,</span> <span class="bp">__FILE__</span><span class="p">)</span>
|
|
|
|
|
<span class="no">FileList</span><span class="o">[</span><span class="s2">"</span><span class="si">#{</span><span class="n">libdir</span><span class="si">}</span><span class="s2">/rocco.rb"</span><span class="p">,</span> <span class="s2">"</span><span class="si">#{</span><span class="n">libdir</span><span class="si">}</span><span class="s2">/rocco/**"</span><span class="o">]</span>
|
|
|
|
|
<span class="k">end</span>
|
|
|
|
|
|
|
|
|
|
<span class="k">end</span>
|
|
|
|
|
<span class="k">end</span></pre></div>
|
|
|
|
|
</td>
|
|
|
|
|
</tr>
|
|
|
|
|
</table>
|
|
|
|
|
</div>
|
|
|
|
|
</body>
|
