mirror of https://github.com/mpastell/Weave.jl
38 lines
22 KiB
HTML
38 lines
22 KiB
HTML
<!DOCTYPE html>
|
|
<html lang="en"><head><meta charset="UTF-8"/><meta name="viewport" content="width=device-width, initial-scale=1.0"/><title>Using Weave · Weave.jl</title><link rel="canonical" href="http://weavejl.mpastell.com/stable/usage/"/><link href="https://fonts.googleapis.com/css?family=Lato|Roboto+Mono" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/fontawesome.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/solid.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.11.2/css/brands.min.css" rel="stylesheet" type="text/css"/><link href="https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.11.1/katex.min.css" rel="stylesheet" type="text/css"/><script>documenterBaseURL=".."</script><script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js" data-main="../assets/documenter.js"></script><script src="../siteinfo.js"></script><script src="../../versions.js"></script><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-dark.css" data-theme-name="documenter-dark"/><link class="docs-theme-link" rel="stylesheet" type="text/css" href="../assets/themes/documenter-light.css" data-theme-name="documenter-light" data-theme-primary/><script src="../assets/themeswap.js"></script></head><body><div id="documenter"><nav class="docs-sidebar"><div class="docs-package-name"><span class="docs-autofit">Weave.jl</span></div><form class="docs-search" action="../search/"><input class="docs-search-query" id="documenter-search-query" name="q" type="text" placeholder="Search docs"/></form><ul class="docs-menu"><li><a class="tocitem" href="../">Weave.jl - Scientific Reports Using Julia</a></li><li><a class="tocitem" href="../getting_started/">Getting started</a></li><li class="is-active"><a class="tocitem" href>Using Weave</a><ul class="internal"><li><a class="tocitem" href="#weave"><span><code>weave</code></span></a></li><li><a class="tocitem" href="#tangle"><span><code>tangle</code></span></a></li><li><a class="tocitem" href="#Supported-Output-Formats"><span>Supported Output Formats</span></a></li><li><a class="tocitem" href="#document-syntax"><span>Document Syntax</span></a></li><li><a class="tocitem" href="#Configuration-via-YAML-Header"><span>Configuration via YAML Header</span></a></li><li><a class="tocitem" href="#Passing-Runtime-Arguments-to-Documents"><span>Passing Runtime Arguments to Documents</span></a></li><li><a class="tocitem" href="#include_weave"><span><code>include_weave</code></span></a></li></ul></li><li><a class="tocitem" href="../publish/">Publishing to HTML and PDF</a></li><li><a class="tocitem" href="../chunk_options/">Chunk Options</a></li><li><a class="tocitem" href="../header/">Header Configuration</a></li><li><a class="tocitem" href="../notebooks/">Working with Jupyter notebooks</a></li><li><a class="tocitem" href="../function_index/">Function index</a></li></ul><div class="docs-version-selector field has-addons"><div class="control"><span class="docs-label button is-static is-size-7">Version</span></div><div class="docs-selector control is-expanded"><div class="select is-fullwidth is-size-7"><select id="documenter-version-selector"></select></div></div></div></nav><div class="docs-main"><header class="docs-navbar"><nav class="breadcrumb"><ul class="is-hidden-mobile"><li class="is-active"><a href>Using Weave</a></li></ul><ul class="is-hidden-tablet"><li class="is-active"><a href>Using Weave</a></li></ul></nav><div class="docs-right"><a class="docs-edit-link" href="https://github.com/JunoLab/Weave.jl/blob/master/doc/src/usage.md" title="Edit on GitHub"><span class="docs-icon fab"></span><span class="docs-label is-hidden-touch">Edit on GitHub</span></a><a class="docs-settings-button fas fa-cog" id="documenter-settings-button" href="#" title="Settings"></a><a class="docs-sidebar-button fa fa-bars is-hidden-desktop" id="documenter-sidebar-button" href="#"></a></div></header><article class="content" id="documenter-page"><h1 id="Using-Weave"><a class="docs-heading-anchor" href="#Using-Weave">Using Weave</a><a id="Using-Weave-1"></a><a class="docs-heading-anchor-permalink" href="#Using-Weave" title="Permalink"></a></h1><p>You can write your documentation and code in input document using Markdown, Noweb or script syntax and use <a href="#Weave.weave"><code>weave</code></a> function to execute to document to capture results and figures.</p><h2 id="weave"><a class="docs-heading-anchor" href="#weave"><code>weave</code></a><a id="weave-1"></a><a class="docs-heading-anchor-permalink" href="#weave" title="Permalink"></a></h2><p>Weave document with markup and julia code using <code>Plots.jl</code> for plots, <code>out_path = :pwd</code> makes the results appear in the current working directory.</p><blockquote><p>A prepared example: <a href="../examples/FIR_design.jmd"><code>Weave.SAMPLE_JL_DOC</code></a></p></blockquote><pre><code class="language-julia"># First add depencies for the example
|
|
using Pkg; Pkg.add.(["Plots", "DSP"])
|
|
using Weave
|
|
weave(Weave.SAMPLE_JL_DOC; out_path=:pwd)</code></pre><article class="docstring"><header><a class="docstring-binding" id="Weave.weave" href="#Weave.weave"><code>Weave.weave</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia">weave(source::AbstractString; kwargs...)</code></pre><p>Weave an input document to output file.</p><p><strong>Keyword options</strong></p><ul><li><code>doctype::Union{Nothing,AbstractString} = nothing</code>: Output document format. By default (i.e. given <code>nothing</code>), Weave will set it automatically based on file extension. You can also manually specify it; see <a href="#Weave.list_out_formats"><code>list_out_formats()</code></a> for the supported formats</li><li><code>informat::Union{Nothing,AbstractString} = nothing</code>: Input document format. By default (i.e. given <code>nothing</code>), Weave will set it automatically based on file extension. You can also specify either of <code>"script"</code>, <code>"markdown"</code>, <code>"notebook"</code>, or <code>"noweb"</code></li><li><code>out_path::Union{Symbol,AbstractString} = :doc</code>: Path where the output is generated can be either of:<ul><li><code>:doc</code>: Path of the source document (default)</li><li><code>:pwd</code>: Julia working directory</li><li><code>"somepath"</code>: <code>String</code> of output directory e.g. <code>"~/outdir"</code>, or of filename e.g. <code>"~/outdir/outfile.tex"</code></li></ul></li><li><code>args::Any = Dict()</code>: A runtime object that is available as <code>WEAVE_ARGS</code> while <code>weave</code>ing</li><li><code>mod::Union{Module,Nothing} = nothing</code>: Module where Weave <code>eval</code>s code. You can pass a <code>Module</code> object, otherwise create an new sandbox module.</li><li><code>fig_path::Union{Nothing,AbstractString} = nothing</code>: Where figures will be generated, relative to <code>out_path</code>. By default (i.e. given <code>nothing</code>), Weave will automatically create <code>figures</code> directory.</li><li><code>fig_ext::Union{Nothing,AbstractString} = nothing</code>: Extension for saved figures e.g. <code>".pdf"</code>, <code>".png"</code>. Default setting depends on <code>doctype</code></li><li><code>cache_path::AbstractString = "cache"</code>: Where of cached output will be saved</li><li><code>cache::Symbol = :off</code>: Controls caching of code:<ul><li><code>:off</code> means no caching (default)</li><li><code>:all</code> caches everything</li><li><code>:user</code> caches based on chunk options</li><li><code>:refresh</code> runs all code chunks and save new cache</li></ul></li><li><code>template::Union{Nothing,AbstractString,Mustache.MustacheTokens} = nothing</code>: Template (file path) or <code>Mustache.MustacheTokens</code>s for <code>md2html</code> or <code>md2tex</code> formats</li><li><code>css::Union{Nothing,AbstractString} = nothing</code>: Path of a CSS file used for md2html format</li><li><code>highlight_theme::Union{Nothing,Type{<:Highlights.AbstractTheme}} = nothing</code>: Theme used for syntax highlighting (defaults to <code>Highlights.Themes.DefaultTheme</code>)</li><li><code>pandoc_options::Vector{<:AbstractString} = String[]</code>: <code>String</code>s of options to pass to pandoc for <code>pandoc2html</code> and <code>pandoc2pdf</code> formats, e.g. <code>["--toc", "-N"]</code></li><li><code>latex_cmd::Vector{<:AbstractString} = ["xelatex", "-shell-escape", "-halt-on-error"]</code>: The command used to make PDF file from .tex</li><li><code>keep_unicode::Bool = false</code>: If <code>true</code>, do not convert unicode characters to their respective latex representation. This is especially useful if a font and tex-engine with support for unicode characters are used</li></ul><div class="admonition is-info"><header class="admonition-header">Note</header><div class="admonition-body"><p>Run Weave from terminal and try to avoid weaving from IJulia or ESS; they tend to mess with capturing output.</p></div></div></div><a class="docs-sourcelink" target="_blank" href="https://github.com/JunoLab/Weave.jl/blob/196d4ca7ce80e65f7365642218c43a8c94d5f286/src/Weave.jl#L92-L124">source</a></section></article><h2 id="tangle"><a class="docs-heading-anchor" href="#tangle"><code>tangle</code></a><a id="tangle-1"></a><a class="docs-heading-anchor-permalink" href="#tangle" title="Permalink"></a></h2><p>Tangling extracts the code from document:</p><article class="docstring"><header><a class="docstring-binding" id="Weave.tangle" href="#Weave.tangle"><code>Weave.tangle</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia">tangle(source::AbstractString; kwargs...)</code></pre><p>Tangle source code from input document to .jl file.</p><p><strong>Keyword options</strong></p><ul><li><code>informat::Union{Nothing,AbstractString} = nothing</code>: Input document format. By default (i.e. given <code>nothing</code>), Weave will set it automatically based on file extension. You can also specify either of <code>"script"</code>, <code>"markdown"</code>, <code>"notebook"</code>, or <code>"noweb"</code></li><li><code>out_path::Union{Symbol,AbstractString} = :doc</code>: Path where the output is generated can be either of:<ul><li><code>:doc</code>: Path of the source document (default)</li><li><code>:pwd</code>: Julia working directory</li><li><code>"somepath"</code>: <code>String</code> of output directory e.g. <code>"~/outdir"</code>, or of filename e.g. <code>"~/outdir/outfile.tex"</code></li></ul></li></ul></div><a class="docs-sourcelink" target="_blank" href="https://github.com/JunoLab/Weave.jl/blob/196d4ca7ce80e65f7365642218c43a8c94d5f286/src/Weave.jl#L57-L69">source</a></section></article><h2 id="Supported-Output-Formats"><a class="docs-heading-anchor" href="#Supported-Output-Formats">Supported Output Formats</a><a id="Supported-Output-Formats-1"></a><a class="docs-heading-anchor-permalink" href="#Supported-Output-Formats" title="Permalink"></a></h2><p>Weave automatically detects the output format based on the file extension. The auto output format detection is handled by <code>detect_doctype(path::AbstractString)</code>:</p><pre><code class="language-julia">function detect_doctype(path::AbstractString)
|
|
_, ext = lowercase.(splitext(path))
|
|
|
|
match(r"^\.(jl|.?md|ipynb)", ext) !== nothing && return "md2html"
|
|
ext == ".rst" && return "rst"
|
|
ext == ".tex" && return "texminted"
|
|
ext == ".txt" && return "asciidoc"
|
|
|
|
return "pandoc"
|
|
end</code></pre><p>You can also manually specify it using the <code>doctype</code> keyword option. You can get a list of supported output formats:</p><article class="docstring"><header><a class="docstring-binding" id="Weave.list_out_formats" href="#Weave.list_out_formats"><code>Weave.list_out_formats</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia">list_out_formats()</code></pre><p>List supported output formats with its description.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/JunoLab/Weave.jl/blob/196d4ca7ce80e65f7365642218c43a8c94d5f286/src/Weave.jl#L50-L54">source</a></section></article><pre><code class="language-julia">list_out_formats()</code></pre><pre class="documenter-example-output">12-element Array{Pair{String,String},1}:
|
|
"github" => "GitHub Markdown"
|
|
"md2tex" => "Weave-styled LaTeX"
|
|
"pandoc2html" => "HTML via intermediate Pandoc Markdown (requires Pandoc 2)"
|
|
"pandoc" => "Pandoc Markdown"
|
|
"pandoc2pdf" => "PDF via intermediate Pandoc Markdown"
|
|
"texminted" => "LaTeX using minted package for code highlighting"
|
|
"md2html" => "Weave-style HTML"
|
|
"rst" => "reStructuredText and Sphinx"
|
|
"multimarkdown" => "MultiMarkdown"
|
|
"md2pdf" => "PDF via Weave-styled LaTeX"
|
|
"asciidoc" => "AsciiDoc"
|
|
"hugo" => "Hugo Markdown (using shortcodes)"</pre><h2 id="document-syntax"><a class="docs-heading-anchor" href="#document-syntax">Document Syntax</a><a id="document-syntax-1"></a><a class="docs-heading-anchor-permalink" href="#document-syntax" title="Permalink"></a></h2><p>Weave uses markdown, Noweb or script syntax for defining the code chunks and documentation chunks. You can also weave Jupyter notebooks. The format is detected based on the file extension, but you can also set it manually using the <code>informat</code> parameter.</p><p>The rules for autodetection are:</p><pre><code class="language-julia">ext == ".jl" && return "script"
|
|
ext == ".jmd" && return "markdown"
|
|
ext == ".ipynb" && return "notebook"
|
|
return "noweb"</code></pre><h3 id="Documentation-Chunks"><a class="docs-heading-anchor" href="#Documentation-Chunks">Documentation Chunks</a><a id="Documentation-Chunks-1"></a><a class="docs-heading-anchor-permalink" href="#Documentation-Chunks" title="Permalink"></a></h3><p>In markdown and Noweb input formats documentation chunks are the parts that aren't inside code delimiters. Documentation chunks can be written with several different markup languages.</p><h3 id="code-chunks"><a class="docs-heading-anchor" href="#code-chunks">Code Chunks</a><a id="code-chunks-1"></a><a class="docs-heading-anchor-permalink" href="#code-chunks" title="Permalink"></a></h3><p>Code chunks are written in different ways in different formats.</p><h4 id="Markdown-Format"><a class="docs-heading-anchor" href="#Markdown-Format">Markdown Format</a><a id="Markdown-Format-1"></a><a class="docs-heading-anchor-permalink" href="#Markdown-Format" title="Permalink"></a></h4><p>Weave code chunks are defined using fenced code blocks, same as with <a href="https://spec.commonmark.org/0.29/#fenced-code-blocks">common markdown</a>:</p><pre><code class="language-markdown"> ```julia
|
|
code
|
|
...
|
|
```</code></pre><p>Weave code chunks can optionally be followed by <a href="../chunk_options/#chunk-options">chunk options</a> on the same line. E.g. the chunk below will hide code itself from generated output:</p><pre><code class="language-markdown"> ```julia, echo = false
|
|
code
|
|
...
|
|
```</code></pre><h4 id="Noweb-Format"><a class="docs-heading-anchor" href="#Noweb-Format">Noweb Format</a><a id="Noweb-Format-1"></a><a class="docs-heading-anchor-permalink" href="#Noweb-Format" title="Permalink"></a></h4><p>Code chunks 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.</p><h3 id="inline-code"><a class="docs-heading-anchor" href="#inline-code">Inline Code</a><a id="inline-code-1"></a><a class="docs-heading-anchor-permalink" href="#inline-code" title="Permalink"></a></h3><p>You can also add inline code to your documents using</p><pre><code class="language-none">`j juliacode`</code></pre><p>or</p><pre><code class="language-none">! juliacode</code></pre><p>syntax.</p><p>The former syntax allows you to insert code <em>anywhere</em> in a line while the <code>!</code> syntax treats the whole line as code, and the code will be replaced with captured output in the weaved document.</p><p>If the code produces figures, the filename or base64 encoded string will be added to output, e.g. to include a Plots figure in markdown you can use:</p><pre><code class="language-none">`)</code></pre><p>or to produce any HTML output:</p><pre><code class="language-none">! display("text/html", "Header from julia");</code></pre><h3 id="Script-Format"><a class="docs-heading-anchor" href="#Script-Format">Script Format</a><a id="Script-Format-1"></a><a class="docs-heading-anchor-permalink" href="#Script-Format" title="Permalink"></a></h3><p>Weave also supports script input format with a markup in comments. These scripts can be executed normally using Julia or published with Weave.</p><p>Lines starting with <code>#'</code>, <code>#%%</code> or <code># %%</code> are treated as document.</p><p>All non-document lines are treated as code. You can set chunk options using lines starting with <code>#+</code> just before code e.g:</p><pre><code class="language-julia">#+ term=true
|
|
hoge # some code comes here</code></pre><p>The format is identical to <a href="http://mpastell.com/pweave/pypublish.html">Pweave</a> and the concept is similar to publishing documents with MATLAB or using Knitr's <a href="http://yihui.name/knitr/demo/stitch/">spin</a>. Weave will remove the first empty space from each line of documentation.</p><div class="admonition is-success"><header class="admonition-header">Tip</header><div class="admonition-body"><ul><li>Here are sample documents:<ul><li><a href="https://github.com/JunoLab/Weave.jl/blob/master/examples/FIR_design.jmd">markdown format</a></li><li><a href="https://github.com/JunoLab/Weave.jl/blob/master/examples/FIR_design.jl">script format</a></li></ul></li><li><a href="../chunk_options/#chunk-options">Details about chunk options</a></li></ul></div></div><h2 id="Configuration-via-YAML-Header"><a class="docs-heading-anchor" href="#Configuration-via-YAML-Header">Configuration via YAML Header</a><a id="Configuration-via-YAML-Header-1"></a><a class="docs-heading-anchor-permalink" href="#Configuration-via-YAML-Header" title="Permalink"></a></h2><p>When <code>weave</code>ing markdown files, you can use YAML header to provide additional metadata and configuration options. See <a href="../header/#Header-Configuration">Header Configuration</a> section for more details.</p><h2 id="Passing-Runtime-Arguments-to-Documents"><a class="docs-heading-anchor" href="#Passing-Runtime-Arguments-to-Documents">Passing Runtime Arguments to Documents</a><a id="Passing-Runtime-Arguments-to-Documents-1"></a><a class="docs-heading-anchor-permalink" href="#Passing-Runtime-Arguments-to-Documents" title="Permalink"></a></h2><p>You can pass arbitrary object to the weaved document using <a href="#Weave.weave"><code>weave</code></a>'s optional argument <code>args</code>. It will be available as <code>WEAVE_ARGS</code> variable in the <code>weave</code>d document.</p><p>This makes it possible to create the same report easily for e.g. different date ranges of input data from a database or from files with similar format giving the filename as input.</p><p>E.g. if you call <code>weave("weavefile.jmd", args = (datalocation = "somedata.h5",))</code>, and then you can retrieve the <code>datalocation</code> in <code>weavefile.jmd</code> as follows: <code>WEAVE_ARGS.datalocation</code></p><h2 id="include_weave"><a class="docs-heading-anchor" href="#include_weave"><code>include_weave</code></a><a id="include_weave-1"></a><a class="docs-heading-anchor-permalink" href="#include_weave" title="Permalink"></a></h2><p>You can call <code>include_weave</code> on a Weave document and run all code chunks within in the current session.</p><article class="docstring"><header><a class="docstring-binding" id="Weave.include_weave" href="#Weave.include_weave"><code>Weave.include_weave</code></a> — <span class="docstring-category">Function</span></header><section><div><pre><code class="language-julia">include_weave(source::AbstractString, informat::Union{Nothing,AbstractString} = nothing)
|
|
include_weave(m::Module, source::AbstractString, informat::Union{Nothing,AbstractString} = nothing)</code></pre><p>Include code from Weave document calling <code>include_string</code> on all code from doc. Code is run in the path of the include document.</p></div><a class="docs-sourcelink" target="_blank" href="https://github.com/JunoLab/Weave.jl/blob/196d4ca7ce80e65f7365642218c43a8c94d5f286/src/Weave.jl#L295-L301">source</a></section></article></article><nav class="docs-footer"><a class="docs-footer-prevpage" href="../getting_started/">« Getting started</a><a class="docs-footer-nextpage" href="../publish/">Publishing to HTML and PDF »</a><div class="flexbox-break"></div><p class="footer-message">Powered by <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> and the <a href="https://julialang.org/">Julia Programming Language</a>.</p></nav></div><div class="modal" id="documenter-settings"><div class="modal-background"></div><div class="modal-card"><header class="modal-card-head"><p class="modal-card-title">Settings</p><button class="delete"></button></header><section class="modal-card-body"><p><label class="label">Theme</label><div class="select"><select id="documenter-themepicker"><option value="documenter-light">documenter-light</option><option value="documenter-dark">documenter-dark</option></select></div></p><hr/><p>This document was generated with <a href="https://github.com/JuliaDocs/Documenter.jl">Documenter.jl</a> on <span class="colophon-date" title="Saturday 3 October 2020 04:19">Saturday 3 October 2020</span>. Using Julia version 1.5.2.</p></section><footer class="modal-card-foot"></footer></div></div></div></body></html>
|