Using Weave
You can write your documentation and code in input document using Markdown, Noweb or script syntax and use weave
function to execute to document to capture results and figures.
Weave
Weave document with markup and julia code using Plots.jl
for plots, out_path = :pwd
makes the results appear in the current working directory.
A prepared example
# First add depencies for the example
using Pkg; Pkg.add.(["Plots", "DSP"])
using Weave
weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), out_path=:pwd)
Weave.weave
— Functionweave(source::AbstractString; kwargs...)
Weave an input document to output file.
Keyword options
doctype::Union{Symbol,AbstractString} = :auto
: Output document format.:auto
will set it automatically based on file extension. You can also manually specify it; seelist_out_formats()
for the supported formatsinformat::Union{Symbol,AbstractString} = :auto
: Input document format.:auto
will set it automatically based on file extension. You can also specify either of"script"
,"markdown"
,"notebook"
, or"noweb"
out_path::Union{Symbol,AbstractString} = :doc
: Path where the output is generated can be either of::doc
: Path of the source document (default):pwd
: Julia working directory"somepath"
:String
of output directory e.g."~/outdir"
, or of filename e.g."~/outdir/outfile.tex"
args::Dict = Dict()
: Arguments to be passed to the weaved document; will be available asWEAVE_ARGS
in the documentmod::Union{Module,Nothing} = nothing
: Module where Weaveeval
s code. You can pass aModule
object, otherwise create an new sandbox module.fig_path::AbstractString = "figures"
: Where figures will be generated, relative toout_path
fig_ext::Union{Nothing,AbstractString} = nothing
: Extension for saved figures e.g.".pdf"
,".png"
. Default setting depends ondoctype
cache_path::AbstractString = "cache"
: Where of cached output will be savedcache::Symbol = :off
: Controls caching of code::off
means no caching (default):all
caches everything:user
caches based on chunk options:refresh
runs all code chunks and save new cache
throw_errors::Bool = false
: Iffalse
errors are included in output document and the whole document is executed. Iftrue
errors are thrown when they occurtemplate::Union{Nothing,AbstractString,Mustache.MustacheTokens} = nothing
: Template (file path) orMustache.MustacheTokens
s formd2html
ormd2tex
formatshighlight_theme::Union{Nothing,Type{<:Highlights.AbstractTheme}} = nothing
: Theme used for syntax highlighting (defaults toHighlights.Themes.DefaultTheme
)css::Union{Nothing,AbstractString} = nothing
: Path of a CSS file used for md2html formatpandoc_options::Vector{<:AbstractString} = String[]
:String
s of options to pass to pandoc forpandoc2html
andpandoc2pdf
formats, e.g.["--toc", "-N"]
latex_cmd::AbstractString = "xelatex"
: The command used to make PDF file from .texlatex_keep_unicode::Bool = false
: Iftrue
, 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
Run Weave from terminal and try to avoid weaving from IJulia or ESS; they tend to mess with capturing output.
Tangle
Tangling extracts the code from document:
Weave.tangle
— Functiontangle(source::AbstractString; kwargs...)
Tangle source code from input document to .jl file.
Keyword options
informat::Union{Symbol,AbstractString} = :auto
: Input document format.:auto
will set it automatically based on file extension. You can also specify either of"script"
,"markdown"
,"notebook"
, or"noweb"
out_path::Union{Symbol,AbstractString} = :doc
: Path where the output is generated can be either of::doc
: Path of the source document (default):pwd
: Julia working directory"somepath"
:String
of output directory e.g."~/outdir"
, or of filename e.g."~/outdir/outfile.tex"
Supported output formats
Weave automatically detects the output format based on the file extension. The auto output format detection is handled by detect_doctype(path::AbstractString)
:
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
You can also manually specify it using the doctype
keyword option. You can get a list of supported output formats:
Weave.list_out_formats
— Functionlist_out_formats()
List supported output formats
list_out_formats()
github: GitHub markdown
md2tex: Julia markdown to latex
pandoc2html: Markdown to HTML (requires Pandoc 2)
pandoc: Pandoc markdown
pandoc2pdf: Pandoc markdown
tex: Latex with custom code environments
texminted: Latex using minted for highlighting
md2html: Julia markdown to html
rst: reStructuredText and Sphinx
multimarkdown: MultiMarkdown
md2pdf: Julia markdown to latex
asciidoc: AsciiDoc
hugo: Hugo markdown (using shortcodes)
Document syntax
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 informat
parameter.
The rules for autodetection are:
ext == ".jl" && return "script"
ext == ".jmd" && return "markdown"
ext == ".ipynb" && return "notebook"
return "noweb"
Documentation chunks
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.
Code chunks
Markdown format
Markdown code chunks are defined using fenced code blocks with options following on the same line. e.g. to hide code from output you can use:
```julia; echo=false
Inline code
You can also add inline code to your documents using
`j juliacode`
or
! juliacode
syntax. Using the j code
syntax you can insert code anywhere in a line and with the !
syntax the whole line after !
will be executed. The code will be replaced with captured output in the weaved document.
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:
![A plot](`j plot(1:10)`)
or to produce any html output:
! display("text/html", "Header from julia");
Noweb format
Code chunks start with a line marked with <<>>=
or <<options>>=
and end with line marked with @
. The code between the start and end markers is executed and the output is captured to the output document. See chunk options.
Script format
Weave also support script input format with a markup in comments. These scripts can be executed normally using Julia or published with Weave. Documentation is in lines starting with #'
, #%%
or # %%
, and code is executed and results are included in the weaved document.
All lines that are not documentation are treated as code. You can set chunk options using lines starting with #+
just before code e.g. #+ term=true
.
The format is identical to Pweave and the concept is similar to publishing documents with MATLAB or using Knitr's spin. Weave will remove the first empty space from each line of documentation.
Setting document options in header
You can use a YAML header in the beginning of the input document delimited with "–-" to set the document title, author and date e.g. and default document options. Each of Weave command line arguments and chunk options can be set in header using options
field. Below is an example that sets document out_path
and doctype
using the header.
---
title : Weave example
author : Matti Pastell
date: 15th December 2016
options:
out_path : reports/example.md
doctype : github
---
You can also set format specific options. Here is how to set different out_path
for md2html
and md2pdf
and set fig_ext
for both:
---
options:
md2html:
out_path : html
md2pdf:
out_path : pdf
fig_ext : .png
---
Passing arguments to documents
You can pass arguments as Dict
to the weaved document using the args
argument to weave
. The arguments will be available as WEAVE_ARGS
variable in the document.
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.
In order to pass a filename to a document you need call weave
using:
weave("mydoc.jmd", args = Dict("filename" => "somedata.h5"))
and you can access the filename from document as follows:
```julia
print(WEAVE_ARGS["filename"])
```
You can use the out_path
argument to control the name of the output document.
Include Weave document in Julia
You can call include_weave
on a Weave document to run the contents of all code chunks in Julia.
Weave.include_weave
— Functioninclude_weave(source::AbstractString, informat::Union{Symbol,AbstractString} = :auto)
include_weave(m::Module, source::AbstractString, informat::Union{Symbol,AbstractString} = :auto)
Include code from Weave document calling include_string
on all code from doc. Code is run in the path of the include document.