2016-04-21 13:36:55 +02:00
# Using Weave
2019-03-04 14:42:16 +01:00
You can write your documentation and code in input document using Markdown, Noweb or script
2020-03-26 09:35:43 +01:00
syntax and use [`weave` ](@ref ) function to execute to document to capture results and figures.
2016-04-21 13:36:55 +02:00
2020-05-16 10:52:17 +02:00
## `weave`
2016-04-21 13:36:55 +02:00
2018-08-13 14:51:08 +02:00
Weave document with markup and julia code using `Plots.jl` for plots,
2016-04-21 13:36:55 +02:00
`out_path = :pwd` makes the results appear in the current working directory.
2020-05-18 15:59:18 +02:00
> A prepared example: [`Weave.SAMPLE_JL_DOC`](../examples/FIR_design.jmd)
2020-03-26 09:35:43 +01:00
2016-04-21 13:36:55 +02:00
```julia
2020-03-26 17:49:48 +01:00
# First add depencies for the example
2018-08-13 14:51:08 +02:00
using Pkg; Pkg.add.(["Plots", "DSP"])
2016-04-21 13:36:55 +02:00
using Weave
2020-05-18 15:59:18 +02:00
weave(Weave.SAMPLE_JL_DOC; out_path=:pwd)
2016-04-21 13:36:55 +02:00
```
2016-05-18 22:12:01 +02:00
```@docs
2020-03-26 09:35:43 +01:00
weave
2016-05-18 22:12:01 +02:00
```
2016-04-21 13:36:55 +02:00
2020-05-16 10:52:17 +02:00
## `tangle`
2016-04-21 13:36:55 +02:00
Tangling extracts the code from document:
2016-05-18 22:12:01 +02:00
```@docs
2020-03-26 17:49:48 +01:00
tangle
2016-05-18 22:12:01 +02:00
```
2016-04-21 13:36:55 +02:00
2020-05-16 10:52:17 +02:00
## Supported Output Formats
2016-04-21 13:36:55 +02:00
2020-03-27 12:34:06 +01:00
Weave automatically detects the output format based on the file extension.
The auto output format detection is handled by `detect_doctype(path::AbstractString)` :
2016-04-22 15:16:50 +02:00
```julia
2020-03-27 12:34:06 +01:00
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
2016-04-22 15:16:50 +02:00
```
2020-03-27 12:34:06 +01:00
You can also manually specify it using the `doctype` keyword option.
2016-04-21 13:36:55 +02:00
You can get a list of supported output formats:
2020-03-26 09:35:43 +01:00
```@docs
list_out_formats
2016-04-21 13:36:55 +02:00
```
2020-03-26 09:35:43 +01:00
```@example
using Weave # hide
2016-05-18 22:12:01 +02:00
list_out_formats()
```
2016-04-21 13:36:55 +02:00
2020-05-16 10:52:17 +02:00
## [Document Syntax](@id document-syntax)
2016-04-21 13:36:55 +02:00
2019-03-04 14:42:16 +01:00
Weave uses markdown, Noweb or script syntax for defining the code chunks and
2016-12-12 13:05:26 +01:00
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.
2016-04-22 15:16:50 +02:00
The rules for autodetection are:
2016-12-12 20:40:05 +01:00
```julia
2016-04-22 15:16:50 +02:00
ext == ".jl" & & return "script"
ext == ".jmd" & & return "markdown"
2016-12-12 13:05:26 +01:00
ext == ".ipynb" & & return "notebook"
2016-04-22 15:16:50 +02:00
return "noweb"
```
2020-05-24 19:05:48 +02:00
### Documentation Chunks
2016-04-21 13:36:55 +02:00
2020-05-16 13:33:48 +02:00
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.
2016-04-21 13:36:55 +02:00
2020-05-24 19:05:48 +02:00
### [Code Chunks](@id code-chunks)
Code chunks are written in different ways in different formats.
2016-12-15 20:08:49 +01:00
2020-05-24 19:05:48 +02:00
#### Markdown Format
2016-12-15 20:08:49 +01:00
2020-05-24 19:05:48 +02:00
Weave code chunks are defined using fenced code blocks, same as with [common markdown ](https://spec.commonmark.org/0.29/#fenced-code-blocks ):
```markdown
```julia
code
...
```
2019-03-10 22:09:27 +01:00
```
2020-05-24 19:05:48 +02:00
Weave code chunks can optionally be followed by [chunk options ](@ref ) on the same line.
E.g. the chunk below will hide code itself from generated output:
```markdown
```julia, echo = false
code
...
```
2019-03-10 22:09:27 +01:00
```
2016-12-15 20:08:49 +01:00
2020-05-24 19:05:48 +02:00
#### Noweb Format
2019-03-04 14:42:16 +01:00
2020-05-24 19:05:48 +02:00
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.
2019-03-10 18:23:18 +01:00
2020-05-24 19:05:48 +02:00
### [Inline Code](@id inline-code)
2019-03-10 18:23:18 +01:00
2020-05-24 19:05:48 +02:00
You can also add inline code to your documents using
2019-03-10 18:23:18 +01:00
```
`j juliacode`
```
or
```
! juliacode
```
2020-05-24 19:05:48 +02:00
syntax.
2019-03-10 18:23:18 +01:00
2020-05-24 19:05:48 +02:00
The former syntax allows you to insert code _anywhere_ in a line
while the `!` syntax treats the whole line as code,
and the code will be replaced with captured output in the weaved document.
2019-03-10 18:23:18 +01:00
2020-05-24 19:05:48 +02:00
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:
2019-03-10 18:23:18 +01:00
```
![A plot ](`j plot(1:10 )`)
```
2020-05-24 19:05:48 +02:00
or to produce any HTML output:
2019-03-10 18:23:18 +01:00
```
! display("text/html", "Header from julia");
```
2020-05-16 10:52:17 +02:00
### Script Format
2016-12-15 20:08:49 +01:00
2020-05-24 19:05:48 +02:00
Weave also supports script input format with a markup in comments.
2020-05-16 10:52:17 +02:00
These scripts can be executed normally using Julia or published with Weave.
2016-12-15 20:08:49 +01:00
2020-05-16 10:52:17 +02:00
Lines starting with `#'` , `#%%` or `# %%` are treated as document.
2016-12-15 20:08:49 +01:00
2020-05-16 10:52:17 +02:00
All non-document lines are treated as code.
You can set chunk options using lines starting with `#+` just before code e.g:
```julia
#+ term=true
hoge # some code comes here
```
2016-12-15 20:08:49 +01:00
2020-05-16 10:52:17 +02:00
The format is identical to [Pweave ](http://mpastell.com/pweave/pypublish.html ) and the concept is similar to publishing documents with MATLAB or using Knitr's [spin ](http://yihui.name/knitr/demo/stitch/ ).
Weave will remove the first empty space from each line of documentation.
2016-04-21 13:36:55 +02:00
2020-05-24 19:05:48 +02:00
!!! tip
- Here are sample documents:
2020-06-13 21:05:28 +02:00
+ [markdown format ](https://github.com/JunoLab/Weave.jl/blob/master/examples/FIR_design.jmd )
+ [script format ](https://github.com/JunoLab/Weave.jl/blob/master/examples/FIR_design.jl )
2020-05-24 19:05:48 +02:00
- [Details about chunk options ](@ref chunk-options )
2016-12-29 15:34:39 +01:00
2019-03-04 10:10:02 +01:00
2020-05-16 10:52:17 +02:00
## Configuration via YAML Header
2019-03-04 10:10:02 +01:00
2020-05-16 13:49:52 +02:00
When `weave` ing markdown files, you can use YAML header to provide additional metadata and configuration options.
2020-05-16 10:52:17 +02:00
See [Header Configuration ](@ref ) section for more details.
2019-03-04 10:10:02 +01:00
2019-03-05 15:44:10 +01:00
2020-05-16 10:52:17 +02:00
## Passing Runtime Arguments to Documents
2016-12-29 16:06:29 +01:00
2020-09-30 11:43:15 +02:00
You can pass arbitrary object to the weaved document using [`weave` ](@ref )'s optional argument `args` .
It will be available as `WEAVE_ARGS` variable in the `weave` d document.
2016-12-29 16:06:29 +01:00
2020-09-30 11:43:15 +02:00
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.
2016-12-29 16:06:29 +01:00
2020-09-30 12:07:26 +02:00
E.g. if you call `weave("weavefile.jmd", args = (datalocation = "somedata.h5",))` , and then you can retrieve the `datalocation` in `weavefile.jmd` as follows: `WEAVE_ARGS.datalocation`
2018-01-07 11:31:06 +01:00
2020-05-16 10:52:17 +02:00
## `include_weave`
You can call `include_weave` on a Weave document and run all code chunks within in the current session.
2018-01-07 11:31:06 +01:00
```@docs
2020-03-06 02:14:21 +01:00
include_weave
2018-08-13 14:51:08 +02:00
```