From 62de3d60d8d57c0cffa7f962258e1b05ac4a560a Mon Sep 17 00:00:00 2001 From: autodocs Date: Mon, 11 Mar 2019 12:00:13 +0000 Subject: [PATCH] build based on 83e2e0a --- dev/notebooks/index.html | 2 +- dev/usage/index.html | 6 +++--- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/dev/notebooks/index.html b/dev/notebooks/index.html index 4d17c4c..42ff3a5 100644 --- a/dev/notebooks/index.html +++ b/dev/notebooks/index.html @@ -1,2 +1,2 @@ -Working with Jupyter notebooks · Weave.jl
Working with Jupyter notebooks

Working with Jupyter notebooks

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("notebook.ipynb")

Output to Jupyter notebooks

As of Weave 0.5.1. there is new notebook method to convert Weave documents to Jupyter notebooks using nbconvert. The code is not executed by Weave and the output doesn't always work properly, see #116.

Weave.notebook — Function.

notebook(source::String, outpath=:pwd, timeout=-1, nbconvertoptions="")

Convert Weave document source to Jupyter notebook and execute the code using nbconvert. Requires IJulia. Ignores all chunk options

  • out_path: Path where the output is generated. Can be: :doc: Path of the source document, :pwd: Julia working directory, "somepath": Path as a String e.g "/home/mpastell/weaveout"
  • timeout: nbconvert cell timeout in seconds. Defaults to -1 (no timeout)
  • nbconvert_options: string of additional options to pass to nbconvert, such as --allow-errors
source

You might wan't to use the convert_doc method below instead and run the code in Jupyter.

Converting between formats

You can convert between all supported input formats using the convert_doc function.

To convert from script to notebook:

convert_doc("examples/FIR_design.jl", "FIR_design.ipynb")

and from notebooks to markdown use:

convert_doc("FIR_design.ipynb", "FIR_design.jmd")
Weave.convert_doc — Method.

convert_doc(infile::AbstractString, outfile::AbstractString; format = nothing)

Convert Weave documents between different formats

  • infile = Name of the input document
  • outfile = Name of the output document
  • format = Output format (optional). Detected from outfile extension, but can be set to "script", "markdown", "notebook" or "noweb".
source
+Working with Jupyter notebooks · Weave.jl
Working with Jupyter notebooks

Working with Jupyter notebooks

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("notebook.ipynb")

Output to Jupyter notebooks

As of Weave 0.5.1. there is new notebook method to convert Weave documents to Jupyter notebooks using nbconvert. The code is not executed by Weave and the output doesn't always work properly, see #116.

Weave.notebook — Function.

notebook(source::String, outpath=:pwd, timeout=-1, nbconvertoptions="")

Convert Weave document source to Jupyter notebook and execute the code using nbconvert. Requires IJulia. Ignores all chunk options

  • out_path: Path where the output is generated. Can be: :doc: Path of the source document, :pwd: Julia working directory, "somepath": Path as a String e.g "/home/mpastell/weaveout"
  • timeout: nbconvert cell timeout in seconds. Defaults to -1 (no timeout)
  • nbconvert_options: string of additional options to pass to nbconvert, such as --allow-errors
source

You might wan't to use the convert_doc method below instead and run the code in Jupyter.

Converting between formats

You can convert between all supported input formats using the convert_doc function.

To convert from script to notebook:

convert_doc("examples/FIR_design.jl", "FIR_design.ipynb")

and from notebooks to markdown use:

convert_doc("FIR_design.ipynb", "FIR_design.jmd")
Weave.convert_doc — Method.

convert_doc(infile::AbstractString, outfile::AbstractString; format = nothing)

Convert Weave documents between different formats

  • infile = Name of the input document
  • outfile = Name of the output document
  • format = Output format (optional). Detected from outfile extension, but can be set to "script", "markdown", "notebook" or "noweb".
source
diff --git a/dev/usage/index.html b/dev/usage/index.html index 6ab8c62..1749adf 100644 --- a/dev/usage/index.html +++ b/dev/usage/index.html @@ -9,7 +9,7 @@ weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design cache_path = "cache", cache=:off, template = nothing, highlight_theme = nothing, css = nothing, pandoc_options = "", - latex_cmd = "xelatex")

Weave an input document to output file.

Note: Run Weave from terminal and not using IJulia, Juno or ESS, they tend to mess with capturing output.

source

Tangle

Tangling extracts the code from document:

Weave.tangle — Method.

tangle(source ; out_path=:doc, informat="noweb")

Tangle source code from input document to .jl file.

  • informat: "noweb" of "markdown"
  • out_path: Path where the output is generated. Can be: :doc: Path of the source document, :pwd: Julia working directory, "somepath", directory name as a string e.g "/home/mpastell/weaveout"

or filename as string e.g. ~/outpath/outfile.jl.

source

Supported output formats

Weave sets the output format based on the file extension, but you can also set it using doctype option. The rules for detecting the format are:

ext == ".jl" && return "md2html"
+    latex_cmd = "xelatex")

Weave an input document to output file.

Note: Run Weave from terminal and not using IJulia, Juno or ESS, they tend to mess with capturing output.

source

Tangle

Tangling extracts the code from document:

Weave.tangle — Method.

tangle(source ; out_path=:doc, informat="noweb")

Tangle source code from input document to .jl file.

  • informat: "noweb" of "markdown"
  • out_path: Path where the output is generated. Can be: :doc: Path of the source document, :pwd: Julia working directory, "somepath", directory name as a string e.g "/home/mpastell/weaveout"

or filename as string e.g. ~/outpath/outfile.jl.

source

Supported output formats

Weave sets the output format based on the file extension, but you can also set it using doctype option. The rules for detecting the format are:

ext == ".jl" && return "md2html"
 contains(ext, ".md") && return "md2html"
 contains(ext, ".rst") && return "rst"
 contains(ext, ".tex") && return "texminted"
@@ -26,7 +26,7 @@ rst: reStructuredText and Sphinx
 multimarkdown: MultiMarkdown
 md2pdf: Julia markdown to latex
 asciidoc: AsciiDoc
-hugo: Hugo markdown (using shortcodes)
Weave.list_out_formats — Method.

list_out_formats()

List supported output formats

source

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.

The rules for autodetection are:

ext == ".jl" && return "script"
+hugo: Hugo markdown (using shortcodes)
Weave.list_out_formats — Method.

list_out_formats()

List supported output formats

source

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.

The rules for autodetection are:

ext == ".jl" && return "script"
 ext == ".jmd" && return "markdown"
 ext == ".ipynb" && return "notebook"
 return "noweb"

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

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:

 ```julia; echo=false`

Sample document

Inline code

You can also add inline code to your documents using

`j juliacode`

or

! juliacode

syntax. Using the j code syntax you can insert code anywhere in a line and with the ! syntax the whole line after ! will be executed. The code will be replaced with captured output in the weaved document.

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:

![A plot](`j plot(1:10)`)

or to produce any html output:

! display("text/html", "Header from julia");

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.

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.

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.

The format is identical to Pweave and the concept is similar to publishing documents with MATLAB or using Knitr's spin. Weave will remove the first empty space from each line of documentation.

See sample document:

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.

---
@@ -45,4 +45,4 @@ options:
     fig_ext : .png
 ---

Passing arguments to documents

You can pass arguments as dictionary to the weaved document using the args argument to weave. The dictionary will be available as WEAVE_ARGS variable in the document.

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.

In order to pass a filename to a document you need call weave using:

weave("mydoc.jmd", args = Dict("filename" => "somedata.h5"))

and you can access the filename from document as follows:

 ```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.

Weave.include_weave — Function.
include_weave(doc, informat=:auto)

Include code from Weave document calling include_string on all code from doc. Code is run in the path of the include document.

source
+ ```

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.

Weave.include_weave — Function.
include_weave(doc, informat=:auto)

Include code from Weave document calling include_string on all code from doc. Code is run in the path of the include document.

source