mirror of https://github.com/mpastell/Weave.jl
simpler doc APIs
Shuhei Kadowaki
parent
efccb5c7f1
commit
840f1b3b8f
82
src/Weave.jl
82
src/Weave.jl
|
|
@ -21,18 +21,14 @@ end
|
|||
|
||||
|
||||
"""
|
||||
tangle(
|
||||
source::AbstractString;
|
||||
out_path::Union{Symbol,AbstractString} = :doc,
|
||||
informat::Union{Symbol,AbstractString} = :auto
|
||||
)
|
||||
tangle(source::AbstractString; kwargs...)
|
||||
|
||||
Tangle source code from input document to .jl file.
|
||||
|
||||
## Keyword options:
|
||||
## Keyword options
|
||||
|
||||
- `informat = :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 = :doc`: Path where the output is generated can be either of:
|
||||
- `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"`
|
||||
|
|
@ -63,53 +59,35 @@ end
|
|||
|
||||
|
||||
"""
|
||||
weave(
|
||||
source::AbstractString;
|
||||
doctype::Union{Symbol,AbstractString} = :auto,
|
||||
informat::Union{Symbol,AbstractString} = :auto,
|
||||
out_path::Union{Symbol,AbstractString} = :doc,
|
||||
args::Dict = Dict(),
|
||||
mod::Union{Module,Symbol} = :sandbox,
|
||||
fig_path::AbstractString = "figures",
|
||||
fig_ext::Union{Nothing,AbstractString} = nothing,
|
||||
cache_path::AbstractString = "cache",
|
||||
cache::Symbol = :off,
|
||||
throw_errors::Bool = false,
|
||||
template::Union{Nothing,AbstractString,Mustache.MustacheTokens} = nothing,
|
||||
highlight_theme::Union{Nothing,Type{<:Highlights.AbstractTheme}} = nothing,
|
||||
css::Union{Nothing,AbstractString} = nothing,
|
||||
pandoc_options::Vector{<:AbstractString} = String[],
|
||||
latex_cmd::AbstractString = "xelatex",
|
||||
latex_keep_unicode::Bool = false
|
||||
)
|
||||
weave(source::AbstractString; kwargs...)
|
||||
|
||||
Weave an input document to output file.
|
||||
|
||||
## Keyword options
|
||||
|
||||
- `doctype = :auto`: Output document format. `:auto` will set it automatically based on file extension. You can also manually specify it; see [`list_out_formats()`](@ref) for the supported formats
|
||||
- `informat = :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 = :doc`: Path where the output is generated can be either of:
|
||||
- `doctype::Union{Symbol,AbstractString} = :auto`: Output document format. `:auto` will set it automatically based on file extension. You can also manually specify it; see [`list_out_formats()`](@ref) for the supported formats
|
||||
- `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"`
|
||||
- `args = Dict()`: Arguments to be passed to the weaved document; will be available as `WEAVE_ARGS` in the document
|
||||
- `mod = :sandbox`: Module where Weave `eval`s code. Defaults to `:sandbox` to create new sandbox module. You also can also pass a `Module` e.g. `Main`
|
||||
- `fig_path = "figures"`: Where figures will be generated, relative to `out_path`
|
||||
- `fig_ext = nothing`: Extension for saved figures e.g. `".pdf"`, `".png"`. Default setting depends on `doctype`
|
||||
- `cache_path = "cache"`: Where of cached output will be saved
|
||||
- `cache = :off`: Controls caching of code:
|
||||
- `args::Dict = Dict()`: Arguments to be passed to the weaved document; will be available as `WEAVE_ARGS` in the document
|
||||
- `mod::Union{Module,Symbol} = :sandbox`: Module where Weave `eval`s code. Defaults to `:sandbox` to create new sandbox module. You also can also pass a `Module` e.g. `Main`
|
||||
- `fig_path::AbstractString = "figures"`: Where figures will be generated, relative to `out_path`
|
||||
- `fig_ext::Union{Nothing,AbstractString} = nothing`: Extension for saved figures e.g. `".pdf"`, `".png"`. Default setting depends on `doctype`
|
||||
- `cache_path::AbstractString = "cache"`: Where of cached output will be saved
|
||||
- `cache::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 = false`: If `false` errors are included in output document and the whole document is executed. If `true` errors are thrown when they occur
|
||||
- `template = nothing`: Template (file path) or `Mustache.MustacheTokens`s for `md2html` or `md2tex` formats
|
||||
- `highlight_theme = nothing`: Theme used for syntax highlighting (defaults to `Highlights.Themes.DefaultTheme`)
|
||||
- `css = nothing`: Path of a CSS file used for md2html format
|
||||
- `pandoc_options = String[]`: `String`s of options to pass to pandoc for `pandoc2html` and `pandoc2pdf` formats, e.g. `["--toc", "-N"]`
|
||||
- `latex_cmd = "xelatex"`: The command used to make PDF file from .tex
|
||||
- `latex_keep_unicode = false`: If `true`, 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
|
||||
- `throw_errors::Bool = false`: If `false` errors are included in output document and the whole document is executed. If `true` errors are thrown when they occur
|
||||
- `template::Union{Nothing,AbstractString,Mustache.MustacheTokens} = nothing`: Template (file path) or `Mustache.MustacheTokens`s for `md2html` or `md2tex` formats
|
||||
- `highlight_theme::Union{Nothing,Type{<:Highlights.AbstractTheme}} = nothing`: Theme used for syntax highlighting (defaults to `Highlights.Themes.DefaultTheme`)
|
||||
- `css::Union{Nothing,AbstractString} = nothing`: Path of a CSS file used for md2html format
|
||||
- `pandoc_options::Vector{<:AbstractString} = String[]`: `String`s of options to pass to pandoc for `pandoc2html` and `pandoc2pdf` formats, e.g. `["--toc", "-N"]`
|
||||
- `latex_cmd::AbstractString = "xelatex"`: The command used to make PDF file from .tex
|
||||
- `latex_keep_unicode::Bool = false`: If `true`, 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
|
||||
|
||||
!!! note
|
||||
Run Weave from terminal and try to avoid weaving from IJulia or ESS; they tend to mess with capturing output.
|
||||
|
|
@ -186,7 +164,7 @@ function weave(
|
|||
end
|
||||
|
||||
doc.cwd == pwd() && (outname = basename(outname))
|
||||
@info("Report weaved to $outname")
|
||||
@info "Report weaved to $outname"
|
||||
return abspath(outname)
|
||||
# catch err
|
||||
# @warn "Something went wrong during weaving"
|
||||
|
|
@ -202,26 +180,20 @@ weave(doc::AbstractString, doctype::Union{Symbol,AbstractString}) =
|
|||
weave(doc; doctype = doctype)
|
||||
|
||||
"""
|
||||
notebook(
|
||||
source::AbstractString;
|
||||
out_path::Union{Symbol,AbstractString} = :pwd,
|
||||
timeout = -1,
|
||||
nbconvert_options::AbstractString = "",
|
||||
jupyter_path::AbstractString = "jupyter",
|
||||
)
|
||||
notebook(source::AbstractString; kwargs...)
|
||||
|
||||
Convert Weave document `source` to Jupyter notebook and execute the code using `nbconvert`.
|
||||
**Ignores** all chunk options.
|
||||
|
||||
## Keyword options
|
||||
|
||||
- `out_path = :pwd`: Path where the output is generated can be either of:
|
||||
- `out_path::Union{Symbol,AbstractString} = :pwd`: Path where the output is generated can be either of:
|
||||
* `:doc`: Path of the source document
|
||||
* `:pwd`: Julia working directory (default)
|
||||
* `"somepath"`: `String` of output directory e.g. `"~/outdir"`, or of filename e.g. `"~/outdir/outfile.tex"`
|
||||
- `timeout = -1`: nbconvert cell timeout in seconds. Defaults to `-1` (no timeout)
|
||||
- `nbconvert_options = ""`: `String` of additional options to pass to nbconvert, such as `"--allow-errors"`
|
||||
- `jupyter_path = "jupyter"`: Path/command for the Jupyter you want to use. Defaults to `"jupyter"`, which runs whatever is linked/alias to that
|
||||
- `nbconvert_options::AbstractString = ""`: `String` of additional options to pass to nbconvert, such as `"--allow-errors"`
|
||||
- `jupyter_path::AbstractString = "jupyter"`: Path/command for the Jupyter you want to use. Defaults to `"jupyter"`, which runs whatever is linked/alias to that
|
||||
"""
|
||||
function notebook(
|
||||
source::AbstractString;
|
||||
|
|
@ -239,7 +211,7 @@ function notebook(
|
|||
write(f, converted)
|
||||
end
|
||||
|
||||
@info("Running nbconvert")
|
||||
@info "Running nbconvert"
|
||||
out = read(
|
||||
`$jupyter_path nbconvert --ExecutePreprocessor.timeout=$timeout --to notebook --execute $outfile $nbconvert_options --output $outfile`,
|
||||
String,
|
||||
|
|
|
|||
58
src/run.jl
58
src/run.jl
|
|
@ -1,32 +1,46 @@
|
|||
using Base64
|
||||
|
||||
"""
|
||||
run(doc::WeaveDoc; doctype = :auto,
|
||||
mod::Union{Module, Symbol} = :sandbox, out_path=:doc,
|
||||
args=Dict(), fig_path = "figures", fig_ext = nothing,
|
||||
cache_path = "cache", cache = :off, throw_errors=false)
|
||||
run(doc::WeaveDoc; kwargs...)
|
||||
|
||||
Run code chunks and capture output from parsed document.
|
||||
Run code chunks and capture output from the parsed document.
|
||||
|
||||
* `doctype`: :auto = set based on file extension or specify one of the supported formats.
|
||||
See `list_out_formats()`
|
||||
* `out_path`: Path where the output is generated. Can be: `:doc`: Path of the source document, `:pwd`: Julia working directory,
|
||||
`"somepath"`: Path as a AbstractString e.g `"/home/mpastell/weaveout"`
|
||||
* `args`: dictionary of arguments to pass to document. Available as WEAVE_ARGS.
|
||||
* `mod`: Module where Weave `eval`s code. Defaults to `:sandbox`
|
||||
to create new sandbox module, you can also pass a module e.g. `Main`.
|
||||
* `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.
|
||||
## Keyword options
|
||||
|
||||
**Note:** Run command from terminal and not using IJulia, Juno or ESS, they tend to mess with capturing output.
|
||||
- `doctype::Union{Symbol,AbstractString} = :auto`: Output document format. `:auto` will set it automatically based on file extension. You can also manually specify it; see [`list_out_formats()`](@ref) for the supported formats
|
||||
- `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 as `WEAVE_ARGS` in the document
|
||||
- `mod::Union{Module,Symbol} = :sandbox`: Module where Weave `eval`s code. Defaults to `:sandbox` to create new sandbox module. You also can also pass a `Module` e.g. `Main`
|
||||
- `fig_path::AbstractString = "figures"`: Where figures will be generated, relative to `out_path`
|
||||
- `fig_ext::Union{Nothing,AbstractString} = nothing`: Extension for saved figures e.g. `".pdf"`, `".png"`. Default setting depends on `doctype`
|
||||
- `cache_path::AbstractString = "cache"`: Where of cached output will be saved
|
||||
- `cache::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`: If `false` errors are included in output document and the whole document is executed. If `true` errors are thrown when they occur
|
||||
- `latex_keep_unicode::Bool = false`: If `true`, 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
|
||||
|
||||
!!! note
|
||||
Run Weave from terminal and try to avoid weaving from IJulia or ESS; they tend to mess with capturing output.
|
||||
"""
|
||||
function Base.run(doc::WeaveDoc; doctype = :auto,
|
||||
mod::Union{Module, Symbol} = :sandbox, out_path=:doc,
|
||||
args=Dict(), fig_path = "figures", fig_ext = nothing,
|
||||
cache_path = "cache", cache = :off, throw_errors=false, latex_keep_unicode=false)
|
||||
function Base.run(
|
||||
doc::WeaveDoc;
|
||||
doctype::Union{Symbol,AbstractString} = :auto,
|
||||
out_path::Union{Symbol,AbstractString} = :doc,
|
||||
args::Dict = Dict(),
|
||||
mod::Union{Module,Symbol} = :sandbox,
|
||||
fig_path::AbstractString = "figures",
|
||||
fig_ext::Union{Nothing,AbstractString} = nothing,
|
||||
cache_path::AbstractString = "cache",
|
||||
cache::Symbol = :off,
|
||||
throw_errors::Bool = false,
|
||||
latex_keep_unicode::Bool = false
|
||||
)
|
||||
#cache :all, :user, :off, :refresh
|
||||
|
||||
doc.cwd = get_cwd(doc, out_path)
|
||||
|
|
|
|||
Loading…
Reference in New Issue