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

Update docs

pull/202/head
Matti Pastell 2019-03-04 15:42:16 +02:00
parent 6510ea0556
commit d62172ad88
5 changed files with 67 additions and 44 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
README.md
View File

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

32
doc/src/chunk_options.md
View File

@ -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
<<out_width="12cm"; echo=false >>=
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
<<echo = false>>=
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

6
doc/src/index.md
View File

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

22
doc/src/publish.md
View File

@ -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
$$
```

29
doc/src/usage.md
View File

@ -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 `<<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](../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 `<<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](../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