Showcase

This page showcases the various page elements that are supported by Documenter. It should be read side-by-side with its source (docs/src/showcase.md) to see what syntax exactly is used to create the various elements.

Table of contents

A table of contents can be generated with an @contents block. The one for this page renders as

• Showcase
• • Table of contents
  • Basic Markdown
  • Code blocks
  • Mathematics
  • Images
  • Admonitions
  • Lists
  • Tables
  • Footnotes
  • Headings
  • Docstrings
  • Doctesting example
  • Running interactive code

Basic Markdown

Documenter can render all the Markdown syntax supported by the Julia Markdown parser. You can use all the usual markdown syntax, such as bold text and italic text and print("inline code").

Code blocks

Code blocks are rendered as follows:

This is an non-highlighted code block.
... Rendered in monospace.

When the language is specified for the block, e.g. by starting the block with ```julia, the contents gets highlighted appropriately (for the language that are supported by the highlighter).

function foo(x::Integer)
    @show x + 1
end

Mathematics

For mathematics, both inline and display equations are available. Inline equations should be written as LaTeX between two backticks, e.g. ``A x^2 + B x + C = 0``. It will render as $A x^2 + B x + C = 0$.

The LaTeX for display equations must be wrapped in a ```math code block and will render like

\[x_{1,2} = \frac{-B \pm \sqrt{B^2 - 4 A C}}{2A}\]

By default, the HTML output renders equations with KaTeX, but MathJax can optionally be used as well.

Images

Include images using basic Markdown syntax:

The path should be relative to the directory of the current file. Alternatively, use ./ to begin a path relative to the src of the documents, e.g., ./assets/logo.png.

Admonitions

Admonitions are colorful boxes used to highlight parts of the documentation.

Each admonition begins with three !!!, and then the content is indented underneath with four spaces:

!!! note "An optional title"
    Here is something you should pay attention to.

Documenter supports a range of admonition types for different circumstances.

Note admonition

f(x) = x^2

Info admonition

Tip admonition

Warning admonition

Danger admonition

Compat admonition

TODO admonition

Details admonition

Admonitions with type details is rendered as a collapsed <details> block in the HTML output, with the admonition title as the <summary>.

Unknown admonition class

Lists

Tight lists look as follows

• Lorem ipsum dolor sit amet, consectetur adipiscing elit.
• Nulla quis venenatis justo.
• In non sodales eros.

If the lists contain paragraphs or other block level elements, they look like this:

• Morbi et varius nisl, eu semper orci.

  Donec vel nibh sapien. Maecenas ultricies mauris sapien. Nunc et sem ac justo ultricies dignissim ac vitae sem.

• Nulla molestie aliquet metus, a dapibus ligula.

  Morbi pellentesque sodales sollicitudin. Fusce semper placerat suscipit. Aliquam semper tempus ex, non efficitur erat posuere in. Fusce at orci eu ex sagittis commodo.

  Fusce tempus scelerisque egestas. Pellentesque varius nulla a varius fringilla.

  Fusce nec urna eu orci porta blandit.

Numbered lists are also supported

1. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
2. Nulla quis venenatis justo.
3. In non sodales eros.

As are nested lists

• Morbi et varius nisl, eu semper orci.

  Donec vel nibh sapien. Maecenas ultricies mauris sapien. Nunc et sem ac justo ultricies dignissim ac vitae sem.

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  • Nulla quis venenatis justo.
  • In non sodales eros.

• Nulla molestie aliquet metus, a dapibus ligula.

  1. Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  2. Nulla quis venenatis justo.
  3. In non sodales eros.

  Fusce nec urna eu orci porta blandit.

Lists can also be included in other blocks that can contain block level items

• Morbi et varius nisl, eu semper orci.

  Donec vel nibh sapien. Maecenas ultricies mauris sapien. Nunc et sem ac justo ultricies dignissim ac vitae sem.

  • Lorem ipsum dolor sit amet, consectetur adipiscing elit.
  • Nulla quis venenatis justo.
  • In non sodales eros.

Tables

With explicit alignment.

Tables that are too wide should become scrollable.

Footnotes

Footnote references can be added with the [^label] syntax.^[1] The footnote definitions get collected at the bottom of the page.

The footnote label can be an arbitrary string and even consist of block-level elements.^[Clarke61]

Headings

Finally, headings render as follows

Heading level 3

Heading level 4

Heading level 5

Heading level 6

To see an example of a level 1 heading see the page title and for level 2 heading, see the one just under this paragraph.

Note that in docstrings, the headings get rewritten as just bold text right now:

baz(x, f, k)

Docstrings

The key feature of Documenter, of course, is the ability to automatically include docstrings from your package in the manual. The following example docstrings come from the demo DocumenterShowcase module, the source of which can be found in docs/DocumenterShowcase.jl.

To include a docstrings into a manual page, you needs to use an @docs block

```@docs
DocumenterShowcase
```

This will include a single docstring and it will look like this

println("Hello World")

You can include the docstrings corresponding to different function signatures one by one. E.g., the DocumenterShowcase.foo function has two signatures – (::Integer) and (::AbstractString).

```@docs
DocumenterShowcase.foo(::Integer)
```

yielding the following docstring

foo(::Integer)

And now, by having DocumenterShowcase.foo(::AbstractString) in the @docs block will give the other docstring

foo(::AbstractString)

However, if you want, you can also combine multiple docstrings into a single docstring block. The DocumenterShowcase.bar function has the same signatures as

If we just put DocumenterShowcase.bar in an @docs block, it will combine the docstrings as follows:

bar(::Integer)

bar(::AbstractString)

If you have very many docstrings, you may also want to consider using the @autodocs block which can include a whole set of docstrings automatically based on certain filtering options

Both @docs and @autodocs support the canonical=false keyword argument. This can be used to include a docstring more than once

```@docs; canonical=false
DocumenterShowcase.bar
```

We then see the same docstring as above

bar(::Integer)

bar(::AbstractString)

An index of docstrings

The @index block can be used to generate a list of all the docstrings on a page (or even across pages) and will look as follows

• DocumenterShowcase
• Main.DocumenterShowcase.Foo
• Main.DocumenterShowcase.Foo
• Main.DocumenterShowcase.Foo
• Main.DocumenterShowcase.bar
• Main.DocumenterShowcase.baz
• Main.DocumenterShowcase.foo
• Main.DocumenterShowcase.foo

Multiple uses of the same symbol

Sometimes a symbol has multiple docstrings, for example a type definition, inner and outer constructors. The example below shows how to use specific ones in the documentation.

Doctesting example

Often you want to write code example such as this:

julia> f(x) = x^2
f (generic function with 1 method)

julia> f(3)
9

If you write them as a ```jldoctest code block, Documenter can make sure that the doctest has not become outdated. See Doctests for more information.

Script-style doctests are supported too:

2 + 2
# output
4

Setup code

You can have setup code for doctests that gets executed before the actual doctest. For example, the following doctest needs to have the Documenter module to be present.

julia> Documenter.splitexpr(:(Foo.Bar.baz))
(:(Foo.Bar), :(:baz))

This is achieved by the setup keyword to jldoctest.

```jldoctest; setup=:(using Documenter)

The alternative approach is to use the DocTestSetup keys in @meta-blocks, which will apply across multiple doctests.

```@meta
DocTestSetup = quote
  f(x) = x^2
end
```

julia> f(2)
4

The doctests and @meta blocks are evaluated sequentially on each page, so you can always unset the test code by setting it back to nothing.

```@meta
DocTestSetup = nothing
```

Running interactive code

@example block run a code snippet and insert the output into the document. E.g. the following Markdown

```@example
2 + 3
```

becomes the following code-output block pair

2 + 3

5

If the last element can be rendered as an image or text/html etc. (the corresponding Base.show method for the particular MIME type has to be defined), it will be rendered appropriately. e.g.:

using Main: DocumenterShowcase
DocumenterShowcase.SVGCircle("000", "aaa")

This is handy when combined with the Markdown standard library

using Markdown
Markdown.parse("""
`Markdown.MD` objects can be constructed dynamically on the fly and still get rendered "natively".
""")

If the last value in an @example block is a nothing, the standard output from the blocks' evaluation gets displayed instead

println("Hello World")

Hello World

However, do note that if the block prints to standard output, but also has a final non-nothing value, the standard output just gets discarded:

println("Hello World")
42

42

Color output

Output from @repl blocks and @example blocks support colored output, transforming ANSI color codes to HTML.

Colored @example block output

Input:

```@example
code_typed(sqrt, (Float64,))
```

Output:

code_typed(sqrt, (Float64,))

1-element Vector{Any}:
 CodeInfo(
1 ─ %1 = Base.lt_float(x, 0.0)::Bool
└──      goto #3 if not %1
2 ─      invoke Base.Math.throw_complex_domainerror(:sqrt::Symbol, x::Float64)::Union{}
└──      unreachable
3 ─ %5 = Base.Math.sqrt_llvm(x)::Float64
└──      return %5
) => Float64

Colored @repl block output

Input:

```@repl
printstyled("This should be in bold light cyan.", color=:light_cyan, bold=true)
```

Output:

julia> printstyled("This should be in bold cyan.", color=:cyan, bold=true)This should be in bold cyan.

Locally disabled color:

```@repl; ansicolor=false
printstyled("This should be in bold light cyan.", color=:light_cyan, bold=true)
```

julia> printstyled("This should be in bold light cyan.", color=:light_cyan, bold=true)This should be in bold light cyan.

Raw ANSI code output

Regardless of the color setting, when you print the ANSI escape codes directly, coloring is enabled.

for color in 0:15
    print("\e[38;5;$color;48;5;$(color)m  ")
    print("\e[49m", lpad(color, 3), " ")
    color % 8 == 7 && println()
end
print("\e[m")

    0     1     2     3     4     5     6     7
    8     9    10    11    12    13    14    15

REPL-type

@repl block can be used to simulate the REPL evaluation of code blocks. For example, the following block

```@repl
using Statistics
xs = collect(1:10)
median(xs)
sum(xs)
```

It gets expanded into something that looks like as if it was evaluated in the REPL, with the julia> prompt prepended etc.:

julia> using Statistics
julia> xs = collect(1:10)10-element Vector{Int64}:
  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
julia> median(xs)5.5
julia> sum(xs)55

Named blocks

Generally, each blocks gets evaluate in a separate, clean context (i.e. no variables from previous blocks will be polluting the namespace etc). However, you can also re-use a namespace by giving the blocks a name.

```@example block-name
x = 40
```
will show up like this:

x = 40

40

```@example block-name
x + 1
```
will show up like this:

x + 1

41

When you need setup code that you do not wish to show in the generated documentation, you can use an @setup block:

```@setup block-name
x = 42
```

The @setup block essentially acts as a hidden @example block. Any state it sets up, you can access in subsequent blocks with the same name. For example, the following @example block

```@example block-name
x
```

will show up like this:

x

42

You also have continued blocks which do not evaluate immediately.

```@example block-name; continued = true
y = 99
```

y = 99

The continued evaluation only applies to @example blocks and so if you put, for example, an @repl block in between, it will lead to an error, because the y = 99 line of code has not run yet.

```@repl block-name
x
y
```

julia> x42
julia> yERROR: UndefVarError: `y` not defined in `Main.var"Main"`
Suggestion: check for spelling errors or missing imports.

Another @example block with the same name will, however, finish evaluating it. So a block like

```@example block-name
(x, y)
```

will lead to

(x, y)

(42, 99)