Using Weave

You can write your documentation and code in input document using Noweb, Markdown 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 Gadfly for plots, out_path = :pwd makes the results appear in the current working directory.

using Weave
weave(Pkg.dir("Weave","examples","gadfly_sample.mdw"), out_path = :pwd)

Using PyPlot:

weave(Pkg.dir("Weave","examples","julia_sample.mdw"), plotlib="PyPlot", out_path = :pwd)

# Weave.weave — Method.

weave(source ; doctype = :auto, plotlib=:auto,
    informat=:auto, out_path=:doc, args = Dict(),
    fig_path = "figures", fig_ext = nothing,
    cache_path = "cache", cache=:off,
    template = nothing, highlight_theme = nothing, css = nothing
    latex_cmd = "pdflatex")

Weave an input document to output file.

  • doctype: :auto = set based on file extension or specify one of the supported formats. See list_out_formats()
  • plotlib: "PyPlot", "Gadfly" or nothing
  • informat: :auto = set based on file extension or set to "noweb", "markdown" or script
  • out_path: Path where the output is generated. Can be: :doc: Path of the source document, :pwd: Julia working directory, "somepath": output directory as a String e.g "/home/mpastell/weaveout" or filename as string e.g. ~/outpath/outfile.tex.
  • args: dictionary of arguments to pass to document. Available as WEAVE_ARGS
  • fig_path: where figures will be generated, relative to out_path
  • fig_ext: Extension for saved figures e.g. ".pdf", ".png". Default setting depends on doctype.
  • cache_path: where of cached output will be saved.
  • cache: controls caching of code: :off = no caching, :all = cache everything, :user = cache based on chunk options, :refresh, run all code chunks and save new cache.
  • template : Template (file path) for md2html or md2tex formats.
  • highlight_theme : Theme (Highlights.AbstractTheme) for used syntax highlighting
  • css : CSS (file path) used for md2html format
  • latex_cmd the command used to make pdf from .tex

Note: Run Weave from terminal and not using IJulia, Juno or ESS, they tend to mess with capturing output.

Weave from shell

You can also use the weave.jl script under bin directory to weave documents from the shell:

$ ./weave.jl
usage: weave.jl [--doctype DOCTYPE] [--plotlib PLOTLIB]
                [--informat INFORMAT] [--out_path OUT_PATH]
                [--fig_path FIG_PATH] [--fig_ext FIG_EXT] source...

Tangle

Tangling extracts the code from document:

# Weave.tangle — Method.

tangle(source ; out_path=:doc, informat="noweb")

Tangle source code from input document to .jl file.

  • informat: "noweb" of "markdown"
  • out_path: Path where the output is generated. Can be: :doc: Path of the source document, :pwd: Julia working directory, "somepath", directory name as a string e.g "/home/mpastell/weaveout"

or filename as string e.g. ~/outpath/outfile.jl.

Supported formats

Weave sets the output format based on the file extension, but you can also set it using doctype option. The rules for detecting the format are:

ext == ".jl" && return "md2html"
contains(ext, ".md") && return "md2html"
contains(ext, ".rst") && return "rst"
contains(ext, ".tex") && return "texminted"
contains(ext, ".txt") && return "asciidoc"
return "pandoc"

You can get a list of supported output formats:

list_out_formats()

github: Github markdown
md2tex: Julia markdown to latex
pandoc2html: Markdown to HTML (requires Pandoc)
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

# Weave.list_out_formats — Method.

list_out_formats()

List supported output formats

Document syntax

Weave uses noweb, markdown 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"

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.

Documentation chunks

Are the rest of the document (between @ and <<>>= lines and the first chunk be default) and can be written with several different markup languages.

Sample document

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

See sample document:

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.

See sample document:

Inline code

You can also add inline code to your documents using

`j juliacode`

syntax. The code will be replaced with the output of running the code. 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)`)

Passing arguments to documents

You can pass arguments as dictionary to the weaved document using the args argument to weave. The dictionary 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.