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

Update docs

pull/66/head
Matti Pastell 2016-12-15 21:08:49 +02:00
parent a6b74156f6
commit db2de48133
7 changed files with 61 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

15
doc/make_examples.jl
View File

@ -1,22 +1,21 @@
using Weave
weave(joinpath(dirname(@__FILE__),"..","examples","gadfly_md_sample.jmd"),
weave("../examples/gadfly_md_sample.jmd",
informat="markdown", out_path = "build/examples", doctype = "pandoc")
weave(joinpath(dirname(@__FILE__),"..","examples","gadfly_md_sample.jmd"),
weave("../examples/gadfly_md_sample.jmd",
informat="markdown", out_path = "build/examples", doctype = "md2html")
weave(joinpath(dirname(@__FILE__),"..","examples","gadfly_md_sample.jmd"),
weave("../examples/gadfly_md_sample.jmd",
informat="markdown", out_path = "build/examples", doctype = "md2pdf")
cp(joinpath(dirname(@__FILE__),"..","examples","gadfly_md_sample.jmd"),
cp("../examples/gadfly_md_sample.jmd",
"build/examples/gadfly_md_sample.jmd", remove_destination = true)
cp("build/examples/gadfly_md_sample.md",
"build/examples/gadfly_md_sample.txt", remove_destination = true)
weave(joinpath(dirname(@__FILE__),"..","examples","FIR_design.jl"), out_path = "build/examples")
weave(joinpath(dirname(@__FILE__),"..","examples","FIR_design.jl"), doctype = "md2pdf", out_path = "build/examples")
cp(joinpath(dirname(@__FILE__),"..","examples","FIR_design.jl"),
weave("../examples/FIR_design.jl", out_path = "build/examples")
weave("../examples/FIR_design.jl", doctype = "md2pdf", out_path = "build/examples")
cp("../examples/FIR_design.jl",
"build/examples/FIR_design.jl", remove_destination = true)

2
doc/mkdocs.yml
View File

@ -29,7 +29,7 @@ google_analytics:
- 'auto'
extra:
version: 'v0.2.2'
version: 'v0.2.2+'
author:
twitter: 'mpastell'

2
doc/src/getting_started.md
View File

@ -12,7 +12,7 @@ output in different formats:
- HTML: [gadfly_md_sample.html](examples/gadfly_md_sample.html)
- pdf: [gadfly_md_sample.pdf](examples/gadfly_md_sample.pdf)
*Producing HTML and pdf output requires that you have Pandoc and XeLatex (for pdf) installed.*
*Producing pdf output requires that you have XeLatex installed.*
You can Weave the files to your working directory using:

3
doc/src/notebooks.md
View File

@ -3,7 +3,8 @@
## Weaving
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 notebooks as input format, this means you
can weave notebooks to any supported formats. You can't use chunk options with notebooks.
```julia
weave("notebook.ipynb")

37
doc/src/publish.md
View File

@ -1,22 +1,19 @@
# Publishing scripts
# Publishing to html and pdf
You can also also publish html and pdf
documents from Julia scripts with a specific format. Producing HTML and pdf output
requires that you have Pandoc and XeLatex (for pdf) installed and in your path.
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 XeLatex installed and in your path. *The markdown variant is [Julia markdown](http://docs.julialang.org/en/latest/manual/documentation.html#Markdown-syntax-1)*.
These scripts can be executed normally using Julia or published with Weave.
Documentation is written in markdown in lines starting with `#'`, `#%%` or `# %%`,
and code is executed and results are included in the published document.
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.
The format is identical to [Pweave](http://mpastell.com/pweave/pypublish.html)
and the concept is similar to publishing documents with MATLAB or
using Knitr's [spin](http://yihui.name/knitr/demo/stitch/).
Weave will remove the first empty space from each line of documentation.
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`. See the example below for the markup.
```
---
title : Weave example
author : Matti Pastell
date: 15th December 2016
---
```
Here is a a sample document and output:
[FIR_design.jl](examples/FIR_design.jl), [FIR_design.html](examples/FIR_design.html) , [FIR_design.pdf](examples/FIR_design.pdf).
@ -25,11 +22,5 @@ weave("FIR_design.jl")
weave("FIR_design.jl", docformat = "md2pdf")
```
## Other mark ups with scripts
You can also use any Weave supported format in the comments and set the output format
as you would for noweb and markdown inputs. e.g for LaTeX you can use:
```julia
weave("latex_doc.jl", docformat = "texminted")
```
**Note:** docformats `md2pdf` and `md2html` use Julia markdown and `pandoc2pdf` and `pandoc2html`
use Pandoc.

46
doc/src/usage.md
View File

@ -1,6 +1,7 @@
# Using Weave
You can write your documentation and code in input document using Noweb or Markdown syntax and use `weave` function to execute to document to capture results and figures.
You can write your documentation and code in input document using Noweb, Markdown or script
syntax and use `weave` function to execute to document to capture results and figures.
## Weave
@ -59,16 +60,8 @@ return "pandoc"
You can get a list of supported output formats:
```julia
julia> list_out_formats()
pandoc: Pandoc markdown
rst: reStructuredText and Sphinx
texminted: Latex using minted for highlighting
github: Github markdown
md2html: Markdown to HTML (requires Pandoc)
md2pdf: Markdown to pdf (requires Pandoc and xelatex)
asciidoc: AsciiDoc
tex: Latex with custom code environments
```@repl
list_out_formats()
```
```@docs
@ -89,10 +82,10 @@ ext == ".ipynb" && return "notebook"
return "noweb"
```
## Noweb
## 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 for options below.
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/).
### Documentation chunks
@ -100,6 +93,29 @@ Are the rest of the document (between `@` and `<<>>=` lines and the first chunk
[Sample document]( https://github.com/mpastell/Weave.jl/blob/master/examples/julia_sample.mdw)
## Markdown
## Markdown format
Markdown code chunks are defined using fenced code blocks. [See sample document:](https://github.com/mpastell/Weave.jl/blob/master/examples/gadfly_md_sample.jmd)
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)
## 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](http://mpastell.com/pweave/pypublish.html)
and the concept is similar to publishing documents with MATLAB or
using Knitr's [spin](http://yihui.name/knitr/demo/stitch/).
Weave will remove the first empty space from each line of documentation.
[See sample document:](https://github.com/mpastell/Weave.jl/blob/master/examples/FIR_design.jl)

8
examples/FIR_design.jl
View File

@ -1,6 +1,8 @@
#' % FIR filter design with Julia
#' % Matti Pastell
#' % 21th April 2016
#' ---
#' title : FIR filter design with Julia
#' author : Matti Pastell
#' date : 21th April 2016
#' ---
#' # Introduction