From 7a7d8f3dde54aa52f3dc3d993de195c77f6f4dac Mon Sep 17 00:00:00 2001 From: Shuhei Kadowaki Date: Thu, 26 Mar 2020 17:35:43 +0900 Subject: [PATCH] update documentation source accordingly --- doc/src/chunk_options.md | 10 +++++----- doc/src/notebooks.md | 7 +++---- doc/src/usage.md | 20 +++++++++++--------- 3 files changed, 19 insertions(+), 18 deletions(-) diff --git a/doc/src/chunk_options.md b/doc/src/chunk_options.md index c0ad0d0..bdad949 100644 --- a/doc/src/chunk_options.md +++ b/doc/src/chunk_options.md @@ -11,15 +11,15 @@ 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. +* `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 want 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. +* `tangle = true`. Set tangle to `false` to exclude chunk from tangled code. ## Options for figures @@ -37,7 +37,7 @@ Weave currently supports the following chunk options with the following defaults ## 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: +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: ```yaml --- diff --git a/doc/src/notebooks.md b/doc/src/notebooks.md index e659969..1351238 100644 --- a/doc/src/notebooks.md +++ b/doc/src/notebooks.md @@ -21,14 +21,13 @@ see [#116](https://github.com/mpastell/Weave.jl/issues/116). notebook ``` -You might want to use the `convert_doc` method below instead and run the code in Jupyter. +You might want to use the [`convert_doc`](@ref) 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. +You can convert between all supported input formats using the [`convert_doc`](@ref) function. To convert from script to notebook: @@ -43,5 +42,5 @@ convert_doc("FIR_design.ipynb", "FIR_design.jmd") ``` ```@docs -convert_doc(infile::String, outfile::String) +convert_doc(infile::AbstractString, outfile::AbstractString) ``` diff --git a/doc/src/usage.md b/doc/src/usage.md index 55c2ee1..c868082 100644 --- a/doc/src/usage.md +++ b/doc/src/usage.md @@ -1,13 +1,15 @@ # Using Weave 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. +syntax and use [`weave`](@ref) function to execute to document to capture results and figures. ## Weave Weave document with markup and julia code using `Plots.jl` for plots, `out_path = :pwd` makes the results appear in the current working directory. +> A prepared example + ```julia #First add depencies for the example using Pkg; Pkg.add.(["Plots", "DSP"]) @@ -16,7 +18,7 @@ weave(joinpath(dirname(pathof(Weave)), "../examples", "FIR_design.jmd"), out_pat ``` ```@docs -weave(source) +weave ``` ## Tangle @@ -43,12 +45,12 @@ return "pandoc" You can get a list of supported output formats: -```@example -using Weave # hide -list_out_formats() +```@docs +list_out_formats ``` -```@docs +```@example +using Weave # hide list_out_formats() ``` @@ -96,7 +98,7 @@ or ! juliacode ``` -syntax. Using the `j code` syntax you can insert code anywhere in a line and with +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. @@ -169,8 +171,8 @@ 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. +You can pass arguments as `Dict` to the weaved document using the `args` argument +to `weave`. The arguments 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