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

improve documentations around notebooks

pull/296/head
Shuhei Kadowaki 2020-03-27 20:43:33 +09:00
parent a759dc10bd
commit d40e21ea35
2 changed files with 23 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
doc/src/notebooks.md
View File

@ -3,27 +3,30 @@
## Weaving from Jupyter notebooks
Weave supports using Jupyter notebooks as input format, this means you
can weave notebooks to any supported formats. You can't use chunk options with notebooks.
Weave supports using [Jupyter Notebook](https://jupyter.org/)s as input format.
This means you can [`weave`](@ref) notebooks to any supported formats;
by default, it will be weaved to HTML.
```julia
weave("notebook.ipynb")
weave("notebook.ipynb") # will be weaved to HTML
```
!!! warning
You can't use chunk options with notebooks.
## Output to Jupyter notebooks
As of Weave 0.5.1. there is new `notebook` method to convert Weave documents
to Jupyter notebooks using [nbconvert](http://nbconvert.readthedocs.io/en/latest/execute_api.html). The code **is not executed by Weave**
and the output doesn't always work properly,
see [#116](https://github.com/mpastell/Weave.jl/issues/116).
As of Weave 0.5.1. there is new [`notebook`](@ref) method to convert Weave documents to Jupyter notebooks using
[nbconvert](http://nbconvert.readthedocs.io/en/latest/execute_api.html).
```@docs
notebook
```
You might want to use the [`convert_doc`](@ref) method below instead and run the code in Jupyter.
You can specify `jupyter` used to execute the notebook with the `jupyter_path` keyword argument
(this defaults to the `"jupyter"`, i.e. whatever you have linked to that location).
You can select the `jupyter` used to execute the notebook with the `jupyter_path` argument (this defaults to the string "jupyter," i.e., whatever you have linked to that location.)
Instead, you might want to use the [`convert_doc`](@ref) method below and run the code in Jupyter.
## Converting between formats
@ -35,7 +38,7 @@ To convert from script to notebook:
convert_doc("examples/FIR_design.jl", "FIR_design.ipynb")
```
and from notebooks to markdown use:
and from notebook to Markdown use:
```julia
convert_doc("FIR_design.ipynb", "FIR_design.jmd")

11
src/Weave.jl
View File

@ -182,7 +182,8 @@ weave(doc::AbstractString, doctype::Union{Symbol,AbstractString}) =
"""
notebook(source::AbstractString; kwargs...)
Convert Weave document `source` to Jupyter notebook and execute the code using `nbconvert`.
Convert Weave document `source` to Jupyter Notebook and execute the code
using [`nbconvert`](https://nbconvert.readthedocs.io/en/latest/).
**Ignores** all chunk options.
## Keyword options
@ -194,6 +195,14 @@ Convert Weave document `source` to Jupyter notebook and execute the code using `
- `timeout = -1`: nbconvert cell timeout in seconds. Defaults to `-1` (no timeout)
- `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
!!! warning
The code is _**not**_ executed by Weave, but by [`nbconvert`](https://nbconvert.readthedocs.io/en/latest/).
This means that the output doesn't necessarily always work properly; see [#116](https://github.com/mpastell/Weave.jl/issues/116).
!!! note
In order to _just_ convert Weave document to Jupyter Notebook,
use [`convert_doc`](@ref) instead.
"""
function notebook(
source::AbstractString;