diff --git a/doc/assets/FIR_design.pdf b/doc/assets/FIR_design.pdf new file mode 100644 index 0000000..753aac4 Binary files /dev/null and b/doc/assets/FIR_design.pdf differ diff --git a/doc/assets/FIR_design_plots.pdf b/doc/assets/FIR_design_plots.pdf new file mode 100644 index 0000000..fb68bca Binary files /dev/null and b/doc/assets/FIR_design_plots.pdf differ diff --git a/doc/make_examples.jl b/doc/make_examples.jl index 8009ead..34011c9 100644 --- a/doc/make_examples.jl +++ b/doc/make_examples.jl @@ -1,28 +1,30 @@ using Weave -start_dir = pwd() -cd(@__DIR__) -weave("../examples/FIR_design.jmd", - informat="markdown", out_path = "build/examples", doctype = "pandoc") +let start_dir = pwd() + cd(@__DIR__) -weave("../examples/FIR_design.jmd", - informat="markdown", out_path = "build/examples", doctype = "md2html") + weave("../examples/FIR_design.jmd", doctype = "pandoc", out_path = "build/examples") + weave("../examples/FIR_design.jmd", doctype = "md2html", out_path = "build/examples") + weave("../examples/FIR_design_plots.jl", doctype = "md2html", out_path = "build/examples") -cp("../examples/FIR_design.jmd", - "build/examples/FIR_design.jmd", force = true) + # PDF outputs + if haskey(ENV, "TRAVIS") + # in Travis, just cp already generated PDFs + cp("assets/FIR_design.pdf", "build/examples/FIR_design.pdf", force = true) + cp("assets/FIR_design_plots.pdf", "build/examples/FIR_design_plots.pdf", force = true) + else + # otherwise try to generate them + try + weave("../examples/FIR_design.jmd", doctype = "md2pdf", out_path = "assets") + weave("../examples/FIR_design_plots.jl", doctype = "md2pdf", out_path = "assets") + catch err + @error err + end + end -cp("build/examples/FIR_design.md", - "build/examples/FIR_design.txt", force = true) + cp("../examples/FIR_design.jmd", "build/examples/FIR_design.jmd", force = true) + cp("build/examples/FIR_design.md", "build/examples/FIR_design.txt", force = true) + cp("../examples/FIR_design_plots.jl", "build/examples/FIR_design_plots.jl", force = true) -weave("../examples/FIR_design_plots.jl", out_path = "build/examples") - -cp("../examples/FIR_design_plots.jl", - "build/examples/FIR_design_plots.jl", force = true) - -if !haskey(ENV, "TRAVIS") - weave("../examples/FIR_design.jmd", - informat="markdown", out_path = "build/examples", doctype = "md2pdf") - weave("../examples/FIR_design_plots.jl", doctype = "md2pdf", out_path = "build/examples") + cd(start_dir) end - -cd(start_dir) diff --git a/doc/src/getting_started.md b/doc/src/getting_started.md index 8720397..c4eb597 100644 --- a/doc/src/getting_started.md +++ b/doc/src/getting_started.md @@ -10,11 +10,12 @@ First have a look at source document using markdown code chunks and [FIR_design.jmd](../examples/FIR_design.jmd) and then see the output in different formats: -- HTML: [FIR_design.html](../examples/FIR_design.html) -- pdf: [FIR_design.pdf](../examples/FIR_design.pdf) -- Pandoc markdown: [FIR_design.txt](../examples/FIR_design.txt) +- HTML: [`FIR_design.html`](../examples/FIR_design.html) +- PDF: [`FIR_design.pdf`](../examples/FIR_design.pdf) +- Pandoc markdown: [`FIR_design.txt`](../examples/FIR_design.txt) -*Producing pdf output requires that you have XeLateX installed.* +!!! note + Producing PDF output requires that you have XeLateX installed. Add dependencies for the example if needed: @@ -22,20 +23,29 @@ Add dependencies for the example if needed: using Pkg; Pkg.add.(["Plots", "DSP"]) ``` -Weave the files to your working directory using: +Weave the files to your working directory: ```julia using Weave -#HTML -weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), - out_path=:pwd, - doctype = "md2html") -#pdf -weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), - out_path=:pwd, - doctype = "md2pdf") - #Markdown -weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), - doctype="pandoc", - out_path=:pwd) + +# Julia markdown to HTML +weave( + joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"); + doctype = "md2html", + out_path = :pwd +) + +# Julia markdown to PDF +weave( + joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"); + doctype = "md2pdf", + out_path = :pwd +) + +# Julia markdown to Pandoc markdown +weave( + joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"); + doctype = "pandoc", + out_path = :pwd +) ``` diff --git a/doc/src/publish.md b/doc/src/publish.md index b467658..5b97ebb 100644 --- a/doc/src/publish.md +++ b/doc/src/publish.md @@ -1,10 +1,12 @@ -# Publishing to html and pdf +# 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. +You can also publish any supported input format to HTML and PDF documents. -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. +!!! note + Producing PDF output requires that you have XeLaTex 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.: ``` --- title : Weave example @@ -13,37 +15,45 @@ 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). +Here are sample input and outputs: +- input (Julia markdown format): [`FIR_design_plots.jl`](../examples/FIR_design_plots.jl) +- HTML output: [`FIR_design_plots.html`](../examples/FIR_design_plots.html) +- PDF output: [`FIR_design_plots.pdf`](../examples/FIR_design_plots.pdf) +They are generated as follows: ```julia -weave("FIR_design_plots.jl") -weave("FIR_design_plots.jl", docformat = "md2pdf") +weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design_plots.jl")) # default to md2html output format +weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design_plots.jl"), doctype = "md2pdf") ``` -**Note:** docformats `md2pdf` and `md2html` use Julia markdown and `pandoc2pdf` and `pandoc2html` -use Pandoc. +!!! note + `"md2html"` and `"md2pdf"` assume Julia markdown format as an input, + while `pandoc2pdf` and `pandoc2html` assume Noweb input format (i.e. Pandoc markdown). + ## 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. +You can use a custom template with `md2html` and `md2pdf` formats with `template` keyword option, +e.g.: `weave("FIR_design_plots.jl", template = "custom.tpl"`. -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) +As starting point, you can use the existing templates: + +- HTML (`md2html`): [julia_html.tpl](https://github.com/mpastell/Weave.jl/blob/master/templates/julia_html.tpl) +- LaTex (`md2pdf`): [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](https://docs.julialang.org/en/v1/stdlib/Markdown/#). In addition Weave supports few additional Markdown features: +The markdown variant used by Weave is [Julia markdown](https://docs.julialang.org/en/v1/stdlib/Markdown/#). +In addition Weave supports few additional Markdown features: -**Comments** +### Comments You can add comments using html syntax: `` -**Multiline equations** +### Multiline equations You can add multiline equations using: