diff --git a/README.md b/README.md index 6d29c63..a8fd5e9 100644 --- a/README.md +++ b/README.md @@ -3,7 +3,8 @@ [![Build Status](https://travis-ci.org/mpastell/Weave.jl.svg?branch=master)](https://travis-ci.org/mpastell/Weave.jl) [![Build status](https://ci.appveyor.com/api/projects/status/r97pwi9x8ard6xk6/branch/master?svg=true)](https://ci.appveyor.com/project/mpastell/weave-jl/branch/master) [![Coverage Status](https://img.shields.io/coveralls/mpastell/Weave.jl.svg)](https://coveralls.io/r/mpastell/Weave.jl?branch=master) -[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://mpastell.github.io/Weave.jl/stable) +[![](https://img.shields.io/badge/docs-stable-blue.svg)](https://mpastell.github.io/Weave.jl/dev) +[![](https://img.shields.io/badge/docs-dev-blue.svg)](https://mpastell.github.io/Weave.jl/dev) [![](http://joss.theoj.org/papers/10.21105/joss.00204/status.svg)](http://dx.doi.org/10.21105/joss.00204) Weave is a scientific report generator/literate programming tool @@ -16,15 +17,14 @@ and figures. **Current features** -* Noweb, markdown or script syntax for input documents. -* Execute code as terminal or "script" chunks. -* Capture Plots.jl figures *(or Gadfly and PyPlot on julia 0.6)*. -* Supports LaTex, Pandoc, Github markdown, MultiMarkdown, Asciidoc and reStructuredText output * Publish markdown directly to html and pdf using Julia or Pandoc markdown. +* Markdown, script of Noweb syntax for input documents. +* 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 - **Citing Weave:** *Pastell, Matti. 2017. Weave.jl: Scientific Reports Using Julia. The Journal of Open Source Software. http://dx.doi.org/10.21105/joss.00204* ![Weave code and output](http://mpastell.com/images/weave_demo.png) @@ -66,8 +66,9 @@ Documenter.jl with MKDocs generated documentation: ## Editor support -I have made [language-weave](https://atom.io/packages/language-weave) package -for Atom to do the syntax highlighting correctly. +Install [language-weave](https://atom.io/packages/language-weave) to add Weave support to Juno. +It allows running code from Weave documents with usual keybindings and allows preview of +html and pdf output. ## Contributing @@ -76,3 +77,8 @@ I will probably add new features to Weave when I need them myself or if they are ## Contributors You can see the list of contributors on Github: https://github.com/mpastell/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. +- [TuringTutorials](https://github.com/TuringLang/TuringTutorials) uses Weave to convert notebooks to html. diff --git a/doc/src/chunk_options.md b/doc/src/chunk_options.md index 74a7d46..4c97755 100644 --- a/doc/src/chunk_options.md +++ b/doc/src/chunk_options.md @@ -2,15 +2,15 @@ I've mostly followed [Knitr](http://yihui.name/knitr/options)'s naming for chunk options, but not all options are implemented. -Options are separated using ";" and need to be valid Julia expressions. Example: A code chunk that saves and displays a 12 cm wide image and hides the source code: +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 + using Gadfly + x = linspace(0, 2π, 200) + plot(x=x, y = sin(x), Geom.line) + ``` -```julia -<>= -using Gadfly -x = linspace(0, 2π, 200) -plot(x=x, y = sin(x), Geom.line) -@ -``` Weave currently supports the following chunk options with the following defaults: @@ -47,15 +47,13 @@ You can set or change the default chunk options for a document either before running weave or inside the weaved document. You can e.g. use a hidden chunk in the beginning of the source document to set the options: -```julia -<>= -import Weave -Weave.set_chunk_defaults(Dict{Symbol, Any}( - :out_width => "\\0.5linewidth", - :results => "tex" - )) -@ -``` + ```julia; echo = false>>= + import Weave + Weave.set_chunk_defaults(Dict{Symbol, Any}( + :out_width => "\\0.5linewidth", + :results => "tex" + )) + ``` ```@docs diff --git a/doc/src/index.md b/doc/src/index.md index 1f3207d..a58a480 100644 --- a/doc/src/index.md +++ b/doc/src/index.md @@ -8,11 +8,11 @@ and Sweave. **Current features** -* Noweb, markdown or script syntax for input documents. +* 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 *(or Gadfly and PyPlot figures on 0.6)*. +* Capture Plots.jl or Gadfly.jl figures * Supports LaTex, Pandoc, Github markdown, MultiMarkdown, Asciidoc and reStructuredText output -* Publish markdown directly to html and pdf using julia or Pandoc markdown. * Simple caching of results * Convert to and from IJulia notebooks diff --git a/doc/src/publish.md b/doc/src/publish.md index faec77c..a742583 100644 --- a/doc/src/publish.md +++ b/doc/src/publish.md @@ -1,6 +1,6 @@ # Publishing to html and pdf -You can also publish any supported input format using markdown for doc chunks to html and pdf documents. Producing pdf output requires that you have pdflatex installed and in your path. *The markdown variant is [Julia markdown](http://docs.julialang.org/en/latest/manual/documentation.html#Markdown-syntax-1)*. +You can also publish any supported input format using markdown for doc chunks to html and pdf documents. Producing pdf output requires that you have pdflatex installed and in your path. 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. @@ -15,7 +15,7 @@ date: 15th December 2016 Here is a a sample document and output: -[FIR_design_plots.jl](examples/FIR_design_plots.jl), [FIR_design_plots.html](examples/FIR_design_plots.html) , [FIR_design_plots.pdf](examples/FIR_design_plots.pdf). +[FIR_design_plots.jl](../examples/FIR_design_plots.jl), [FIR_design_plots.html](../examples/FIR_design_plots.html) , [FIR_design_plots.pdf](../examples/FIR_design_plots.pdf). ```julia weave("FIR_design_plots.jl") @@ -34,3 +34,21 @@ the existing templates as starting point. For HTML: [julia_html.tpl](https://github.com/mpastell/Weave.jl/blob/master/templates/julia_html.tpl) and LaTex: [julia_tex.tpl](https://github.com/mpastell/Weave.jl/blob/master/templates/julia_tex.tpl) Templates are rendered using [Mustache.jl](https://github.com/jverzani/Mustache.jl). + +## Supported Markdown syntax + +The markdown variant used by Weave is [Julia markdown](http://docs.julialang.org/en/latest/manual/documentation.html#Markdown-syntax-1). 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/doc/src/usage.md b/doc/src/usage.md index f698f4b..95b9e2e 100644 --- a/doc/src/usage.md +++ b/doc/src/usage.md @@ -1,6 +1,6 @@ # Using Weave -You can write your documentation and code in input document using Noweb, Markdown or script +You can write your documentation and code in input document using Markdown, Noweb or script syntax and use `weave` function to execute to document to capture results and figures. ## Weave @@ -27,7 +27,7 @@ Tangling extracts the code from document: tangle(source) ``` -## Supported formats +## 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: @@ -54,7 +54,7 @@ list_out_formats() ## Document syntax -Weave uses noweb, markdown or script syntax for defining the code chunks and +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: @@ -66,26 +66,27 @@ ext == ".ipynb" && return "notebook" return "noweb" ``` -## Noweb format +## Documentation chunks -### Code chunks -start with a line marked with `<<>>=` or `<>=` 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](../chunk_options/). +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. -### Documentation chunks +## Code chunks -Are the rest of the document (between `@` and `<<>>=` lines and the first chunk be default) and can be written with several different markup languages. - -[Sample document]( https://github.com/mpastell/Weave.jl/blob/master/examples/julia_sample.mdw) - -## Markdown format +### 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` -[See sample document:](https://github.com/mpastell/Weave.jl/blob/master/examples/gadfly_md_sample.jmd) +[Sample document]( https://github.com/mpastell/Weave.jl/blob/master/examples/FIR_design.jmd) -## Script format + +### Noweb format + +Code chunks start with a line marked with `<<>>=` or `<>=` 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](../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