mirror of https://github.com/mpastell/Weave.jl
write documentation for dynamic header
Shuhei Kadowaki
parent
6100083c9e
commit
98abd5e92e
|
|
@ -12,6 +12,7 @@ makedocs(
|
|||
"getting_started.md",
|
||||
"usage.md",
|
||||
"publish.md",
|
||||
"header.md",
|
||||
"chunk_options.md",
|
||||
"notebooks.md",
|
||||
"function_index.md",
|
||||
|
|
|
|||
|
|
@ -8,6 +8,7 @@ Options are separated using ";" and need to be valid Julia expressions. Example:
|
|||
|
||||
Weave currently supports the following chunk options with the following defaults:
|
||||
|
||||
|
||||
## Options for code
|
||||
|
||||
- `echo = true`: Echo the code in the output document. If `false` the source code will be hidden.
|
||||
|
|
@ -21,6 +22,7 @@ Weave currently supports the following chunk options with the following defaults
|
|||
- `hold = false`: Hold all results until the end of the chunk.
|
||||
- `tangle = true`: Set tangle to `false` to exclude chunk from tangled code.
|
||||
|
||||
|
||||
## Options for figures
|
||||
|
||||
- `fig_width = 6`: Figure width passed to plotting library.
|
||||
|
|
@ -42,7 +44,7 @@ You can set the default chunk options (and `weave` arguments) for a document usi
|
|||
```yaml
|
||||
---
|
||||
options:
|
||||
out_width : 50%
|
||||
out_width : 50%
|
||||
---
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,88 @@
|
|||
# Header Configuration
|
||||
|
||||
When `weave`ing a markdown document, you use YAML header to provide additional metadata and configuration options.
|
||||
A YAML header should be in the beginning of the input document delimited with `---`.
|
||||
|
||||
|
||||
!!! warning
|
||||
YAML header configuration is only supported when `weave`ing [Julia markdown documents](@ref document-syntax).
|
||||
|
||||
|
||||
## Document Metadata
|
||||
|
||||
You can set additional document metadata in YAML header.
|
||||
When `weave`ing to Julia markdown documents to HTML or PDF, Weave respects the following metadata specification:
|
||||
- `title`
|
||||
- `author`
|
||||
- `date`
|
||||
|
||||
An example:
|
||||
```yaml
|
||||
---
|
||||
title : Header Example
|
||||
author : Shuhei Kadowaki
|
||||
date: 16th May 2020
|
||||
---
|
||||
```
|
||||
|
||||
!!! note
|
||||
You can also have other metadata, but they won't appear in the resulting HTML and PDF.
|
||||
If you weave to Julia markdown to GitHub/Hugo markdown, all the metadata will be preserved.
|
||||
|
||||
### Dynamic Metadata
|
||||
|
||||
The metadata can be "dynamic"; if you have [inline code](@ref) within YAML header, they will be evaluated _after_ evaluating all the chunks and replaced with the results.
|
||||
|
||||
The example document below will set `date` metadata dynamically.
|
||||
Note that `Date` is available since the chunk is evaluated first.
|
||||
```md
|
||||
---
|
||||
title : Header Example
|
||||
author : Shuhei Kadowaki
|
||||
date: `j Date(now())`
|
||||
---
|
||||
|
||||
```julia; echo = false
|
||||
using Datas
|
||||
```
|
||||
```
|
||||
|
||||
|
||||
## Configuration Options
|
||||
|
||||
Each of keyword arguments of [`weave`](@ref) can be set in the YAML header under `options` field.
|
||||
You can also set [Chunks Options](@ref) there that will be applied globally.
|
||||
|
||||
The example below sets `out_path` and `doctype` options and overwrites `term` and `wrap` chunk options:
|
||||
```yaml
|
||||
---
|
||||
title : Header Example
|
||||
author : Shuhei Kadowaki
|
||||
date: 16th May 2020
|
||||
options:
|
||||
out_path: relative/path/to/this/document
|
||||
doctype: github
|
||||
term: true
|
||||
wrap: false
|
||||
---
|
||||
```
|
||||
|
||||
!!! note
|
||||
- configurations specified within the YAML header have higher precedence than those specified via `weave` keyword arguments
|
||||
- chunk options specified within each chunk have higher precedence than the global global chunk options specified within the YAML header
|
||||
|
||||
|
||||
## Format Specific Options
|
||||
|
||||
The header configurations can be format specific.
|
||||
Here is how to set different `out_path` for `md2html` and `md2pdf` and set `fig_ext` globally:
|
||||
```yaml
|
||||
---
|
||||
options:
|
||||
md2html:
|
||||
out_path : html
|
||||
md2pdf:
|
||||
out_path : pdf
|
||||
fig_ext : .png
|
||||
---
|
||||
```
|
||||
|
|
@ -1,4 +1,3 @@
|
|||
|
||||
# Weave.jl - Scientific Reports Using Julia
|
||||
|
||||
This is the documentation of [Weave.jl](http://github.com/mpastell/weave.jl).
|
||||
|
|
@ -22,10 +21,18 @@ and [Sweave](https://stat.ethz.ch/R-manual/R-patched/library/utils/doc/Sweave.pd
|
|||
|
||||
|
||||
|
||||
## Contents
|
||||
|
||||
## Index
|
||||
|
||||
```@contents
|
||||
Pages = ["getting_started.md", "usage.md",
|
||||
"publish.md", "chunk_options.md", "notebooks.md",
|
||||
"function_index.md"]
|
||||
Pages = [
|
||||
"index.md",
|
||||
"getting_started.md",
|
||||
"usage.md",
|
||||
"publish.md",
|
||||
"header.md",
|
||||
"chunk_options.md",
|
||||
"notebooks.md",
|
||||
"function_index.md",
|
||||
]
|
||||
```
|
||||
|
|
|
|||
|
|
@ -3,7 +3,7 @@
|
|||
You can write your documentation and code in input document using Markdown, Noweb or script
|
||||
syntax and use [`weave`](@ref) function to execute to document to capture results and figures.
|
||||
|
||||
## Weave
|
||||
## `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.
|
||||
|
|
@ -21,7 +21,7 @@ weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), out_pat
|
|||
weave
|
||||
```
|
||||
|
||||
## Tangle
|
||||
## `tangle`
|
||||
|
||||
Tangling extracts the code from document:
|
||||
|
||||
|
|
@ -29,7 +29,7 @@ Tangling extracts the code from document:
|
|||
tangle
|
||||
```
|
||||
|
||||
## Supported output formats
|
||||
## 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)`:
|
||||
|
|
@ -59,7 +59,7 @@ using Weave # hide
|
|||
list_out_formats()
|
||||
```
|
||||
|
||||
## Document syntax
|
||||
## [Document Syntax](@id 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.
|
||||
|
|
@ -73,13 +73,13 @@ ext == ".ipynb" && return "notebook"
|
|||
return "noweb"
|
||||
```
|
||||
|
||||
## Documentation chunks
|
||||
## 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
|
||||
## Code Chunks
|
||||
|
||||
### Markdown format
|
||||
### 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:
|
||||
|
||||
|
|
@ -89,7 +89,7 @@ Markdown code chunks are defined using fenced code blocks with options following
|
|||
|
||||
[Sample document]( https://github.com/mpastell/Weave.jl/blob/master/examples/FIR_design.jmd)
|
||||
|
||||
## Inline code
|
||||
## [Inline Code](@id inline-code)
|
||||
|
||||
You can also add inline code to your documents using
|
||||
|
||||
|
|
@ -121,60 +121,38 @@ or to produce any html output:
|
|||
```
|
||||
|
||||
|
||||
### Noweb format
|
||||
### 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](../chunk_options/).
|
||||
|
||||
|
||||
### Script format
|
||||
### 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.
|
||||
These scripts can be executed normally using Julia or published with Weave.
|
||||
|
||||
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`.
|
||||
Lines starting with `#'`, `#%%` or `# %%` are treated as document.
|
||||
|
||||
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/).
|
||||
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
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
|
||||
[See sample document:](https://github.com/mpastell/Weave.jl/blob/master/examples/FIR_design.jl)
|
||||
|
||||
## 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.
|
||||
## Configuration via YAML Header
|
||||
|
||||
When `weave`ing markdown files, you use YAML header to provide additional metadata and configuration options.
|
||||
See [Header Configuration](@ref) section for more details.
|
||||
|
||||
|
||||
```yaml
|
||||
---
|
||||
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
|
||||
## Passing Runtime 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.
|
||||
|
|
@ -192,18 +170,18 @@ weave("mydoc.jmd", args = Dict("filename" => "somedata.h5"))
|
|||
and you can access the filename from document as follows:
|
||||
|
||||
```
|
||||
```julia
|
||||
print(WEAVE_ARGS["filename"])
|
||||
```
|
||||
```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.
|
||||
## `include_weave`
|
||||
|
||||
You can call `include_weave` on a Weave document and run all code chunks within in the current session.
|
||||
|
||||
```@docs
|
||||
include_weave
|
||||
|
|
|
|||
Loading…
Reference in New Issue