8. Example

This is an example generated with Literate based on this source file: example.jl. You are seeing the HTML-output which Documenter has generated based on a markdown file generated with Literate. The corresponding notebook can be viewed in nbviewer here: example.ipynb, and opened in binder here: example.ipynb, and the plain script output can be found here: example.jl.

It is recommended to have the source file available when reading this, to better understand how the syntax in the source file corresponds to the output you are seeing.

Basic syntax

The basic syntax for Literate is simple, lines starting with # is interpreted as markdown, and all the other lines are interpreted as code. Here is some code:

x = 1//3
y = 2//5

2//5

In markdown sections we can use markdown syntax. For example, we can write text in italic font, text in bold font and use links.

It is possible to filter out lines depending on the output using the #md, #nb, #jl and #src tags (see Filtering lines):

• This line starts with #md and is thus only visible in the markdown output.

The source file is parsed in chunks of markdown and code. Starting a line with #- manually inserts a chunk break. For example, if we want to display the output of the following operations we may insert #- in between. These two code blocks will now end up in different @example-blocks in the markdown output, and two different notebook cells in the notebook output.

x + y

11//15

x * y

2//15

Output capturing

Code chunks are by default placed in Documenter @example blocks in the generated markdown. This means that the output will be captured in a block when Documenter is building the docs. In notebooks the output is captured in output cells, if the execute keyword argument is set to true. Output to stdout/stderr is also captured.

function foo()
    println("This string is printed to stdout.")
    return [1, 2, 3, 4]
end

foo()

4-element Vector{Int64}:
 1
 2
 3
 4

Just like in the REPL, outputs ending with a semicolon hides the output:

1 + 1;

Both Documenter's @example block and notebooks can display images. Here is an example where we generate a simple plot using the Plots.jl package

using Plots
x = range(0, stop=6π, length=1000)
y1 = sin.(x)
y2 = cos.(x)
plot(x, [y1, y2])

Custom processing

It is possible to give Literate custom pre- and post-processing functions. For example, here we insert a placeholder value y = 321 in the source, and use a preprocessing function that replaces it with y = 321 in the rendered output.

x = 123

123

In this case the preprocessing function is defined by

function pre(s::String)
    s = replace(s, "x = 123" => "y = 321")
    return s
end

pre (generic function with 1 method)

Documenter.jl interaction

In the source file it is possible to use Documenter.jl style references, such as @ref and @id. These will be filtered out in the notebook output. For example, here is a link, but it is only visible as a link if you are reading the markdown output. We can also use equations:

\[\int_\Omega \nabla v \cdot \nabla u\ \mathrm{d}\Omega = \int_\Omega v f\ \mathrm{d}\Omega\]

using Documenters math syntax. Documenters syntax is automatically changed to \begin{equation} ... \end{equation} in the notebook output to display correctly.

This page was generated using Literate.jl.