mirror of https://github.com/mpastell/Weave.jl
179 lines
8.6 KiB
HTML
179 lines
8.6 KiB
HTML
<!doctype html>
|
||
|
||
<meta charset="utf-8">
|
||
|
||
<title>Weave</title>
|
||
|
||
<link rel="stylesheet" type="text/css"
|
||
href="https://cdnjs.cloudflare.com/ajax/libs/codemirror/4.5.0/codemirror.min.css">
|
||
|
||
<link rel="stylesheet" type="text/css" href="static/custom.css">
|
||
|
||
<h1 class='package-header'>Weave</h1>
|
||
|
||
<div class="markdown">
|
||
<p>This is the documentation of <a href="http://github.com/mpastell/weave.jl">Weave.jl</a>. Weave is a scientific report generator/literate programming tool for Julia. It resembles <a href="http://mpastell.com/pweave">Pweave</a> and, Knitr and Sweave.</p>
|
||
<p>You can write your documentation and code in input document using Nowed or Markdown syntax and use <code>weave</code> function to execute to document to capture results and figures.</p>
|
||
<p><strong>Current features</strong></p>
|
||
<ul><li>Noweb or markdown syntax for input documents.
|
||
</li><li>Execute code as terminal or "script" chunks.
|
||
</li><li>Capture PyPlot, Gadfly or Winston figures.
|
||
</li><li>Supports LaTex, Pandoc and Github markdown and reStructuredText output
|
||
</li></ul>
|
||
<h1>Document syntax</h1>
|
||
<p>Weave uses noweb or markdown syntax for defining the code chunks and documentation chunks.</p>
|
||
<h2>Noweb</h2>
|
||
<h3>Code chunks</h3>
|
||
<p>start with a line marked with <code><<>>=</code> or <code><<options>>=</code> and end with line marked with <code>@</code>. The code between the start and end markers is executed and the output is captured to the output document. See for options below.</p>
|
||
<h3>Documentation chunks</h3>
|
||
<p>Are the rest of the document (between <code>@</code> and <code><<>>=</code> lines and the first chunk be default) and can be written with several different markup languages.</p>
|
||
<p><a href=" https://github.com/mpastell/Weave.jl/blob/master/examples/julia_sample.mdw">Sample document</a></p>
|
||
<h2>Markdown</h2>
|
||
<p>Markdown code chunks are defined using fenced code blocks. <a href="https://github.com/mpastell/Weave.jl/blob/master/examples/gadfly_sample.jmd">See sample document:</a></p>
|
||
<h1>Chunk options</h1>
|
||
<p>I've tried to follow <a href="http://yihui.name/knitr/options">Knitr</a>'s naming for chunk options, but not all options are implemented.</p>
|
||
<p>Options are separated using ";" and need to be valid Julia expressions. Example: A code chunk that saves and displays a 12 cm wide image and hides the source code:</p>
|
||
<pre><code><<fig_width=5; echo=false >>=
|
||
using Gadfly
|
||
x = linspace(0, 2π, 200)
|
||
plot(x=x, y = sin(x), Geom.line)
|
||
@</code></pre>
|
||
<p>Weave currently supports the following chunk options with the following defaults:</p>
|
||
<p><strong>Options for code</strong></p>
|
||
<ul><li><code>echo = true</code>. Echo the code in the output document. If <code>false</code> the source code will be hidden.
|
||
</li><li><code>results = "markup"</code>. The output format of the printed results. "markup" for literal block, "hidden" for hidden results or anything else for raw output (I tend to use ‘tex’ for Latex and ‘rst’ for rest. Raw output is useful if you wan’t to e.g. create tables from code chunks.
|
||
</li><li><code>eval = true</code>. Evaluate the code chunk. If false the chunk won’t be executed.
|
||
</li><li><code>term=false</code>. If true the output emulates a REPL session. Otherwise only stdout and figures will be included in output.
|
||
</li><li><code>label</code>. Chunk label, will be used for figure labels in Latex as fig:label
|
||
</li><li><code>wrap=true</code>. Wrap long lines from output.
|
||
</li></ul>
|
||
<p><strong>Options for figures</strong></p>
|
||
<ul><li><code>fig_width</code>. Figure width defined in markup, default depends on the output format.
|
||
</li><li><code>out_width</code>. Width of saved figure.
|
||
</li><li><code>out_height</code>. Height of saved figure.
|
||
</li><li><code>dpi</code>=96. Resolution of saved figures.
|
||
</li><li><code>fig_cap</code>. Figure caption.
|
||
</li><li><code>label</code>. Chunk label, will be used for figure labels in Latex as fig:label
|
||
</li><li><code>fig_ext</code>. File extension (format) of saved figures.
|
||
</li><li><code>fig_pos="htpb"</code>. Figure position in Latex.
|
||
</li><li><code>fig_env="figure"</code>. Figure environment in Latex.
|
||
</li></ul>
|
||
<h1>Usage</h1>
|
||
<p>Run from julia using Gadfly for plots:</p>
|
||
<pre><code>using Weave
|
||
weave(Pkg.dir("Weave","examples","gadfly_sample.mdw"))</code></pre>
|
||
<p>Using Winston for plots (Julia 0.3 only):</p>
|
||
<pre><code>weave(Pkg.dir("Weave","examples","winston_sample.mdw"),
|
||
plotlib="Winston", doctype="pandoc")</code></pre>
|
||
<p>Using PyPlot:</p>
|
||
<pre><code>weave(Pkg.dir("Weave","examples","julia_sample.mdw"), plotlib="PyPlot")</code></pre>
|
||
<h2>File formats</h2>
|
||
<p>You can get a list of supported output formats:</p>
|
||
<pre><code>julia> list_out_formats()
|
||
pandoc: Pandoc markdown
|
||
rst: reStructuredText and Sphinx
|
||
texminted: Latex using minted for highlighting
|
||
github: Github markdown
|
||
tex: Latex with custom code environments</code></pre>
|
||
</div>
|
||
<h1 id='module-reference'>Reference</h1>
|
||
<ul class='index'>
|
||
<li >
|
||
<strong>methods:</strong>
|
||
</li>
|
||
<li >
|
||
<ul >
|
||
<li >
|
||
<a href='#list_out_formats()'>list_out_formats()</a></li>
|
||
<li >
|
||
<a href='#tangle(source)'>tangle(source)</a></li>
|
||
<li >
|
||
<a href='#weave(source)'>weave(source)</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
<div class='entries'>
|
||
<div class='entry'>
|
||
<div id='list_out_formats()' class='entry-name category-method'>
|
||
<div class='category'>[method] — </div> list_out_formats()
|
||
</div>
|
||
<div class='entry-body'>
|
||
<div class="markdown">
|
||
<p>List supported output formats</p>
|
||
</div>
|
||
<div class='entry-meta'>
|
||
<strong>Details:</strong>
|
||
<table class='meta-table'>
|
||
<tr >
|
||
<td><strong>source:</strong></td><td >
|
||
<a href='https://github.com/mpastell/Weave.jl/tree/0d170ead3af69555939621d8e44aa784131acea1/src/Weave.jl#L43'>Weave/src/Weave.jl:43</a></td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class='entry'>
|
||
<div id='tangle(source)' class='entry-name category-method'>
|
||
<div class='category'>[method] — </div> tangle(source)
|
||
</div>
|
||
<div class='entry-body'>
|
||
<div class="markdown">
|
||
<p>Tangle source code from input document to .jl file.</p>
|
||
<p><strong>parameters:</strong></p>
|
||
<pre><code>tangle(source ; out_path=:doc, informat="noweb")</code></pre>
|
||
<ul><li><code>informat</code>: <code>"noweb"</code> of <code>"markdown"</code>
|
||
</li><li><code>out_path</code>: Path where the output is generated. Can be: <code>:doc</code>: Path of the source document, <code>:pwd</code>: Julia working directory, <code>"somepath"</code>: Path as a string e.g <code>"/home/mpastell/weaveout"</code>
|
||
</li></ul>
|
||
</div>
|
||
<div class='entry-meta'>
|
||
<strong>Details:</strong>
|
||
<table class='meta-table'>
|
||
<tr >
|
||
<td><strong>source:</strong></td><td >
|
||
<a href='https://github.com/mpastell/Weave.jl/tree/0d170ead3af69555939621d8e44aa784131acea1/src/Weave.jl#L64'>Weave/src/Weave.jl:64</a></td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class='entry'>
|
||
<div id='weave(source)' class='entry-name category-method'>
|
||
<div class='category'>[method] — </div> weave(source)
|
||
</div>
|
||
<div class='entry-body'>
|
||
<div class="markdown">
|
||
<p>Weave an input document to output file.</p>
|
||
<p><strong>parameters:</strong></p>
|
||
<pre><code>weave(source ; doctype = "pandoc", plotlib="Gadfly",
|
||
informat="noweb", out_path=:doc, fig_path = "figures", fig_ext = nothing)</code></pre>
|
||
<ul><li><code>doctype</code>: see <code>list_out_formats()</code>
|
||
</li><li><code>plotlib</code>: <code>"PyPlot"</code>, <code>"Gadfly"</code>, or <code>"Winston"</code>
|
||
</li><li><code>informat</code>: <code>"noweb"</code> of <code>"markdown"</code>
|
||
</li><li><code>out_path</code>: Path where the output is generated. Can be: <code>:doc</code>: Path of the source document, <code>:pwd</code>: Julia working directory, <code>"somepath"</code>: Path as a string e.g <code>"/home/mpastell/weaveout"</code>
|
||
</li><li><code>fig_path</code>: where figures will be generated, relative to out_path
|
||
</li><li><code>fig_ext</code>: Extension for saved figures e.g. <code>".pdf"</code>, <code>".png"</code>. Default setting depends on <code>doctype</code>.
|
||
</li></ul>
|
||
<p><strong>Note:</strong> Run Weave from terminal and not using IJulia, Juno or ESS, they tend to mess with capturing output.</p>
|
||
</div>
|
||
<div class='entry-meta'>
|
||
<strong>Details:</strong>
|
||
<table class='meta-table'>
|
||
<tr >
|
||
<td><strong>source:</strong></td><td >
|
||
<a href='https://github.com/mpastell/Weave.jl/tree/0d170ead3af69555939621d8e44aa784131acea1/src/Weave.jl#L109'>Weave/src/Weave.jl:109</a></td>
|
||
</tr>
|
||
</table>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
|
||
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script>
|
||
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/codemirror/4.5.0/codemirror.min.js"></script>
|
||
<script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/codemirror/4.5.0/mode/julia/julia.min.js"></script>
|
||
|
||
|
||
|
||
<script type="text/javascript" src="static/custom.js"></script>
|
||
|