mirrors
/
Weave.jl
mirror of https://github.com/mpastell/Weave.jl
1
0
Fork 0
Code Issues Releases Wiki Activity

Merge pull request #334 from JunoLab/avi/deprecate 

deprecate `options`, change to `weave_options`:
pull/339/head
Shuhei Kadowaki 2020-05-18 23:44:15 +09:00 committed by GitHub
parent 5e5cb875cf 500d77c9ca
commit 129a654b1d
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
15 changed files with 98 additions and 60 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

27
NEWS.md
View File

@ -1,20 +1,23 @@
# Release notes for Weave.jl
## Release notes for Weave.jl
### v0.4.1
* Disable precompilation due to warnings from depencies
* Disable precompilation due to warnings from dependencies
* Fix deprecation warnings for Julia 0.6
* Fix PyPlot for Julia 0.6
* Support citations in `pandoc2html` and `pandoc2pdf` output
* Fix extra whitespace when `term=true`
* Fix mime type priority for `md2html`
### V0.4.0
* Support passing arguments to document using `args` option
* Add `include_weave` for including code from Weave documents
* Add support for inline code chunks
* Remove generated figure files when publishing to html and pdf
### v0.3.0
* Add support for YAML title block
@ -25,11 +28,13 @@
* Fix extra whitespace from code chunk output
* Improved GR and GLVisualize support with Plots
### v0.2.2
* Add IJulia notebook as input format
* Add `convert_doc` method to convert between input formats
### v0.2.1
* Fix critical hanging on Windows using proper handling of redirect_stdout
@ -37,6 +42,7 @@
output in published HTML documents.
* Fix semicolons for `term=true`
### v0.2
* Move to Julia 0.5 only
@ -57,6 +63,7 @@
- Fix parsing of lone variables from chunks
- Fix error with md2html formatter and dates #38
### v0.1.2
27th April 2016
@ -66,6 +73,7 @@
* Improve doctype autodetection
* Improved regex for parsing markdown input format
### v0.1.1
* Change pandoc output to use inline images if there is no caption.
@ -81,6 +89,7 @@
* Autodetect input and output formats based on filename
* Allow `out_path` be a file or directory.
### v0.1.0
19th April 2016
@ -97,6 +106,7 @@
- Chunks are now represented with their own type. Allows multiple dispatch
and easier implementation of new chunks.
### 0.0.4
4th January 2015
@ -106,6 +116,7 @@
* New option: `out_path` for controlling where weaved documents and figures are saved
* Command line script `bin/weave.jl` for calling weave from command line
### 0.0.3
9th December 2014
@ -121,8 +132,8 @@
7th December 2014
* First release
* Noweb and markdown input formats
* Support for Gadfly, Winston and PyPlot figures
* Term and script chunks
* Support for markdown, tex and rst output
First release:
- Noweb and markdown input formats
- Support for Gadfly, Winston and PyPlot figures
- Term and script chunks
- Support for markdown, tex and rst output

21
README.md
View File

@ -40,25 +40,26 @@ using Pkg
Pkg.add("Weave")
```
## Usage
Run from julia using Plots.jl for plots:
```julia
# First add depencies for the example
using Pkg; Pkg.add.(["Plots", "DSP"])
# Use Weave
using Weave
weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), out_path=:pwd)
# add depencies for the example
using Pkg; Pkg.add(["Plots", "DSP"])
weave(Weave.SAMPLE_JMD_DOC, out_path = :pwd)
```
If you have LaTeX installed you can also weave directly to pdf.
```julia
weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), out_path = :pwd, doctype = "md2pdf")
weave(Weave.SAMPLE_JMD_DOC), out_path = :pwd, doctype = "md2pdf")
```
NOTE: `Weave.SAMPLE_JMD_DOC` is the path of [this document](./examples/FIR_design.jmd).
## Documentation
Documenter.jl with MKDocs generated documentation:
@ -66,6 +67,7 @@ Documenter.jl with MKDocs generated documentation:
[![](https://img.shields.io/badge/docs-stable-blue.svg)](http://weavejl.mpastell.com/stable/)
[![](https://img.shields.io/badge/docs-dev-blue.svg)](http://weavejl.mpastell.com/dev/)
## Editor support
Install [language-weave](https://atom.io/packages/language-weave) to add Weave support to Juno.
@ -75,16 +77,19 @@ html and pdf output.
The [Julia extension for Visual Studio Code](https://www.julia-vscode.org/)
adds Weave support to [Visual Studio Code](https://code.visualstudio.com/).
## Contributing
You can contribute to this package by opening issues on GitHub or implementing things yourself and making a pull request.
We'd also appreciate more example documents written using Weave.
## Contributors
You can see the list of contributors on GitHub: https://github.com/JunoLab/Weave.jl/graphs/contributors .
Thanks for the important additions, fixes and comments.
## Example projects using Weave
- [DiffEqTutorials.jl](https://github.com/JuliaDiffEq/DiffEqTutorials.jl) uses Weave to output tutorials (`.jmd` documents) to html, pdf and Jupyter notebooks.

13
doc/src/chunk_options.md
View File

@ -1,4 +1,4 @@
# Chunk options
# Chunk Options
I've mostly followed [Knitr](http://yihui.name/knitr/options)'s naming for chunk options, but not all options are implemented.
@ -9,7 +9,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
## Options for Code
- `echo = true`: Echo the code in the output document. If `false` the source code will be hidden.
- `results = "markup"`: The output format of the printed results. `"markup"` for literal block, `"hidden"` for hidden results, or anything else for raw output (I tend to use `"tex"` for Latex and `"rst"` for rest). Raw output is useful if you want to e.g. create tables from code chunks.
@ -23,7 +23,7 @@ Weave currently supports the following chunk options with the following defaults
- `tangle = true`: Set tangle to `false` to exclude chunk from tangled code.
## Options for figures
## Options for Figures
- `fig_width = 6`: Figure width passed to plotting library.
- `fig_height = 4`: Figure height passed to plotting library.
@ -37,13 +37,14 @@ Weave currently supports the following chunk options with the following defaults
- `fig_env = "figure"`: Figure environment in Latex.
## Set default chunk options
## Set Default Chunk Options
You can set the default chunk options (and `weave` arguments) for a document using the YAML header `options` field. E.g. to set the default `out_width` of all figures you can use:
You can set the default chunk options (and `weave` arguments) for a document using `weave_options` key in YAML [Header Configuration](@ref).
E.g. to set the default `out_width` of all figures you can use:
```yaml
---
options:
weave_options:
out_width : 50%
---
```

27
doc/src/getting_started.md
View File

@ -5,10 +5,8 @@ The best way to get started using Weave.jl is to look at the example input and
output documents. Examples for different formats are included in the packages
[`examples`](https://github.com/JunoLab/Weave.jl/tree/master/examples) directory.
First have a look at source document using markdown code chunks and
[Plots.jl](https://github.com/JuliaPlots/Plots.jl) for figures:
[FIR_design.jmd](../examples/FIR_design.jmd) and then see the
output in different formats:
First have a look at source document using markdown code chunks and [Plots.jl](https://github.com/JuliaPlots/Plots.jl) for figures:
[FIR_design.jmd](../examples/FIR_design.jmd) (its path is bound to `Weave.SAMPLE_JMD_DOC`) and then see the output in different formats:
- HTML: [`FIR_design.html`](../examples/FIR_design.html)
- PDF: [`FIR_design.pdf`](../examples/FIR_design.pdf)
@ -29,23 +27,14 @@ Weave the files to your working directory:
using Weave
# Julia markdown to HTML
weave(
joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd");
doctype = "md2html",
out_path = :pwd
)
weave(Weave.SAMPLE_JMD_DOC; doctype = "md2html", out_path = :pwd)
# Julia markdown to PDF
weave(
joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd");
doctype = "md2pdf",
out_path = :pwd
)
weave(Weave.SAMPLE_JMD_DOC; doctype = "md2pdf", out_path = :pwd)
# Julia markdown to Pandoc markdown
weave(
joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd");
doctype = "pandoc",
out_path = :pwd
)
weave(Weave.SAMPLE_JMD_DOC; doctype = "pandoc", out_path = :pwd)
```
!!! tips
`Weave.SAMPLE_JMD_DOC` is the path of [FIR_design.jmd](../examples/FIR_design.jmd).

4
doc/src/header.md
View File

@ -59,7 +59,7 @@ The example below sets `out_path` and `doctype` options and overwrites `term` an
title : Header Example
author : Shuhei Kadowaki
date: 16th May 2020
options:
weave_options:
out_path: relative/path/to/this/document
doctype: github
term: true
@ -91,7 +91,7 @@ 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:
weave_options:
md2html:
out_path : html
md2pdf:

9
doc/src/publish.md
View File

@ -16,16 +16,19 @@ date: 15th December 2016
```
Here are sample input and outputs:
- input (Julia markdown format): [`FIR_design_plots.jl`](../examples/FIR_design_plots.jl)
- input (Julia markdown format): [`FIR_design_plots.jl`](../examples/FIR_design_plots.jl) (its path is bound to `Weave.SAMPLE_JL_DOC`)
- HTML output: [`FIR_design_plots.html`](../examples/FIR_design_plots.html)
- PDF output: [`FIR_design_plots.pdf`](../examples/FIR_design_plots.pdf)
They are generated as follows:
```julia
weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design_plots.jl")) # default to md2html output format
weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design_plots.jl"), doctype = "md2pdf")
weave(Weave.SAMPLE_JL_DOC)) # default to md2html output format
weave(Weave.SAMPLE_JL_DOC; doctype = "md2pdf")
```
!!! tips
`Weave.SAMPLE_JL_DOC` is the path of [FIR_design.jl](../examples/FIR_design.jl).
!!! note
`"md2html"` and `"md2pdf"` assume Julia markdown format as an input,
while `pandoc2pdf` and `pandoc2html` assume Noweb input format (i.e. Pandoc markdown).

4
doc/src/usage.md
View File

@ -8,13 +8,13 @@ syntax and use [`weave`](@ref) function to execute to document to capture result
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
> A prepared example: [`Weave.SAMPLE_JL_DOC`](../examples/FIR_design.jmd)
```julia
# 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.SAMPLE_JL_DOC; out_path=:pwd)
```
```@docs

7
examples/FIR_design.jmd
View File

@ -22,6 +22,13 @@ If you're viewing the published version have a look at the
[source](FIR_design_plots.jl) to see the markup.
<!-- this setup dependencies, but doesn't appear in the generated document -->
```julia; echo = false; results = "hidden"
using Pkg
"Plots" ∉ keys(Pkg.project().dependencies) && Pkg.add("Plots")
"DSP" ∉ keys(Pkg.project().dependencies) && Pkg.add("DSP")
```
# FIR Filter Design

6
examples/markdown_beamer.jmd
View File

@ -1,7 +1,7 @@
---
title : A minimal beamer example using Weave markdown
author : Matti Pastell
options :
title: A minimal beamer example using Weave markdown
author: Matti Pastell
weave_options:
doctype : md2pdf
out_path : pdf
template : beamer.tpl

12
src/Weave.jl
View File

@ -5,7 +5,13 @@ using Highlights, Mustache, Requires
const PKG_DIR = normpath(@__DIR__, "..")
const TEMPLATE_DIR = normpath(PKG_DIR, "templates")
const WEAVE_OPTION_NAME = "options" # TODO: rename to "weave_options"
const WEAVE_OPTION_NAME = "weave_options"
const WEAVE_OPTION_NAME_DEPRECATED = "options" # remove this when tagging v0.11
# keeps paths of sample documents for easy try
const SAMPLE_JMD_DOC = normpath(PKG_DIR, "examples", "FIR_design.jmd")
const SAMPLE_JL_DOC = normpath(PKG_DIR, "examples", "FIR_design.jl")
function __init__()
@require Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80" include("plots.jl")
@ -124,6 +130,10 @@ function weave(
# overwrites options with those specified in header, that are needed for running document
# NOTE: these YAML options can NOT be given dynamically
weave_options = get(doc.header, WEAVE_OPTION_NAME, Dict())
if haskey(doc.header, WEAVE_OPTION_NAME_DEPRECATED)
@warn "Weave: `options` key is deprecated. Use `weave_options` key instead."
weave_options = get(doc.header, WEAVE_OPTION_NAME_DEPRECATED, Dict())
end
if !isempty(weave_options)
doctype = get(weave_options, "doctype", doctype)
specific_options!(weave_options, doctype)

4
src/format.jl
View File

@ -98,6 +98,10 @@ function restore_header!(doc)
# only strips Weave headers
delete!(doc.header, WEAVE_OPTION_NAME)
if haskey(doc.header, WEAVE_OPTION_NAME_DEPRECATED)
@warn "Weave: `options` key is deprecated. Use `weave_options` key instead."
delete!(doc.header, WEAVE_OPTION_NAME_DEPRECATED)
end
isempty(doc.header) && return
# restore remained headers as `DocChunk`

8
src/reader/reader.jl
View File

@ -17,6 +17,14 @@ function WeaveDoc(source, informat = nothing)
end
end
end
if haskey(header, WEAVE_OPTION_NAME_DEPRECATED)
@warn "Weave: `options` key is deprecated. Use `weave_options` key instead."
for key in keys(chunk_defaults)
if (val = get(header[WEAVE_OPTION_NAME_DEPRECATED], string(key), nothing)) !== nothing
chunk_defaults[key] = val
end
end
end
return WeaveDoc(
source,

4
test/documents/gadfly_formats_test.jnw
View File

@ -1,6 +1,6 @@
---
options :
out_path : gadfly
weave_options:
out_path: gadfly
---
<<fig_cap="sin(x) function."; label="sin_fun"; fig_pos="ht">>=

8
test/documents/markdown_beamer.jmd
View File

@ -1,8 +1,8 @@
---
title : A minimal beamer example using Weave markdown
author : Matti Pastell
options :
out_path : inline
title: A minimal beamer example using Weave markdown
author: Matti Pastell
weave_options:
out_path: inline
---
```julia; echo=false

4
test/test_header.jl
View File

@ -5,7 +5,7 @@ using Weave: separate_header_text, parse_header, specific_options!
@testset "header separation" begin
header_body = """
options:
weave_options:
foo: bar
"""
@ -79,7 +79,7 @@ end
header = parse_header("""
---
options:
weave_options:
out_path: reports # should be overwrote
md2html:
out_path : html/