diff --git a/previews/PR294/chunk_options/index.html b/previews/PR294/chunk_options/index.html index 7f45212..2903db3 100644 --- a/previews/PR294/chunk_options/index.html +++ b/previews/PR294/chunk_options/index.html @@ -2,4 +2,4 @@ Chunk options · Weave.jl
Edit on GitHub

Chunk options

I've mostly followed Knitr's naming for chunk options, but not all options are implemented.

Options are separated using ";" and need to be valid Julia expressions. Example: markdown code chunk that saves and displays a 12 cm wide image and hides the source code:

julia; out_width="12cm"; echo=false

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.
  • 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 wan’t to e.g. create tables from code chunks.
  • eval = true. Evaluate the code chunk. If false the chunk won’t be executed.
  • term=false. If true the output emulates a REPL session. Otherwise only stdout and figures will be included in output.
  • label. Chunk label, will be used for figure labels in Latex as fig:label
  • wrap = true. Wrap long lines from output.
  • line_width = 75. Line width for wrapped lines.
  • cache = false. Cache results, depends on cache parameter on weave function.
  • 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. Figure width passed to plotting library e.g. 800
  • fig_height Figure height passed to plotting library
  • out_width. Width of saved figure in output markup e.g. "50%", "12cm", 0.5\linewidth
  • out_height. Height of saved figure in output markup
  • dpi=96. Resolution of saved figures.
  • fig_cap. Figure caption.
  • label. Chunk label, will be used for figure labels in Latex as fig:label
  • fig_ext. File extension (format) of saved figures.
  • fig_pos="!h". Figure position in Latex.
  • fig_env="figure". Figure environment in Latex.

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:

---
 options:
       out_width : 50%
----

You can also set or change the default chunk options for a document either before weave using the set_chunk_defaults function.

Weave.set_chunk_defaults — Function
set_chunk_defaults(opts::Dict{Symbol, Any})

Set default options for code chunks, use get_chunk_defaults to see the current values.

E.g.: set default dpi to 200 and fig_width to 8

julia> set_chunk_defaults(Dict{Symbol, Any}(:dpi => 200, fig_width => 8))
source
+---

You can also set or change the default chunk options for a document either before weave using the set_chunk_defaults function.

Weave.set_chunk_defaults — Function
set_chunk_defaults(opts::Dict{Symbol, Any})

Set default options for code chunks, use get_chunk_defaults to see the current values.

E.g.: set default dpi to 200 and fig_width to 8

julia> set_chunk_defaults(Dict{Symbol, Any}(:dpi => 200, fig_width => 8))
source
Weave.get_chunk_defaults — Function

get_chunk_defaults()

Get default options used for code chunks.

source
Weave.restore_chunk_defaults — Function

restore_chunk_defaults()

Restore Weave.jl default chunk options

source
diff --git a/previews/PR294/function_index/index.html b/previews/PR294/function_index/index.html index 231bc10..048b9a1 100644 --- a/previews/PR294/function_index/index.html +++ b/previews/PR294/function_index/index.html @@ -1,2 +1,2 @@ -Function index · Weave.jl
Edit on GitHub
+Function index · Weave.jl
Edit on GitHub
diff --git a/previews/PR294/getting_started/index.html b/previews/PR294/getting_started/index.html index 1763e44..57a5b17 100644 --- a/previews/PR294/getting_started/index.html +++ b/previews/PR294/getting_started/index.html @@ -11,4 +11,4 @@ weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design #Markdown weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), doctype="pandoc", - out_path=:pwd) + out_path=:pwd) diff --git a/previews/PR294/index.html b/previews/PR294/index.html index e028b16..dc18b5c 100644 --- a/previews/PR294/index.html +++ b/previews/PR294/index.html @@ -1,2 +1,2 @@ -Weave.jl - Scientific Reports Using Julia · Weave.jl
Edit on GitHub

Weave.jl - Scientific Reports Using Julia

This is the documentation of Weave.jl. Weave is a scientific report generator/literate programming tool for Julia. It resembles Pweave, knitr, R Markdown, and Sweave.

Current features

  • Markdown, script of Noweb syntax for input documents
  • Publish markdown directly to html and pdf using Julia or Pandoc markdown
  • Execute code as terminal or "script" chunks
  • Capture Plots.jl or Gadfly.jl figures
  • Supports LaTex, Pandoc, GitHub markdown, MultiMarkdown, Asciidoc and reStructuredText output
  • Simple caching of results
  • Convert to and from IJulia notebooks

Weave in Juno demo

Contents

+Weave.jl - Scientific Reports Using Julia · Weave.jl
Edit on GitHub

Weave.jl - Scientific Reports Using Julia

This is the documentation of Weave.jl. Weave is a scientific report generator/literate programming tool for Julia. It resembles Pweave, knitr, R Markdown, and Sweave.

Current features

  • Markdown, script of Noweb syntax for input documents
  • Publish markdown directly to html and pdf using Julia or Pandoc markdown
  • Execute code as terminal or "script" chunks
  • Capture Plots.jl or Gadfly.jl figures
  • Supports LaTex, Pandoc, GitHub markdown, MultiMarkdown, Asciidoc and reStructuredText output
  • Simple caching of results
  • Convert to and from IJulia notebooks

Weave in Juno demo

Contents

diff --git a/previews/PR294/notebooks/index.html b/previews/PR294/notebooks/index.html index f3987aa..a24ac22 100644 --- a/previews/PR294/notebooks/index.html +++ b/previews/PR294/notebooks/index.html @@ -1,2 +1,2 @@ -Working with Jupyter notebooks · Weave.jl
Edit on GitHub

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; out_path=:pwd, timeout=-1, nbconvert_options="", jupyter_path = "jupyter")

Convert Weave document source to Jupyter notebook and execute the code using nbconvert. 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
  • jupyter_path: Path/command for the Jupyter you want to use. Defaults to "jupyter," which runs whatever is linked/alias to that.
source

You might want to use the convert_doc method below instead and run the code in Jupyter.

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

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
Edit on GitHub

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; out_path=:pwd, timeout=-1, nbconvert_options="", jupyter_path = "jupyter")

Convert Weave document source to Jupyter notebook and execute the code using nbconvert. 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
  • jupyter_path: Path/command for the Jupyter you want to use. Defaults to "jupyter," which runs whatever is linked/alias to that.
source

You might want to use the convert_doc method below instead and run the code in Jupyter.

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

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/previews/PR294/publish/index.html b/previews/PR294/publish/index.html index 49209a9..f5045d0 100644 --- a/previews/PR294/publish/index.html +++ b/previews/PR294/publish/index.html @@ -6,4 +6,4 @@ date: 15th December 2016 ---

Here is a a sample document and output:

FIRdesignplots.jl, FIRdesignplots.html , FIRdesignplots.pdf.

weave("FIR_design_plots.jl")
 weave("FIR_design_plots.jl", docformat = "md2pdf")

Note: docformats md2pdf and md2html use Julia markdown and pandoc2pdf and pandoc2html use Pandoc.

Templates

You can use a custom template with md2pdf and md2html formats with template argument (e.g) weave("FIR_design_plots.jl", template = "custom.tpl"). You can use the existing templates as starting point.

For HTML: julia_html.tpl and LaTex: julia_tex.tpl

Templates are rendered using Mustache.jl.

Supported Markdown syntax

The markdown variant used by Weave is Julia markdown. In addition Weave supports few additional Markdown features:

Comments

You can add comments using html syntax: <!-- -->

Multiline equations

You can add multiline equations using:

$$
 x^2 = x*x
-$$
+$$ diff --git a/previews/PR294/search/index.html b/previews/PR294/search/index.html index 7115eca..887653a 100644 --- a/previews/PR294/search/index.html +++ b/previews/PR294/search/index.html @@ -1,2 +1,2 @@ -Search · Weave.jl

Loading search...

    +Search · Weave.jl

    Loading search...

      diff --git a/previews/PR294/usage/index.html b/previews/PR294/usage/index.html index 0eafc7d..2ad0ae1 100644 --- a/previews/PR294/usage/index.html +++ b/previews/PR294/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.

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

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

      ---
@@ -46,4 +46,4 @@ options:
 ---

      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_weave(m::Module, 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
      +include_weave(m::Module, 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