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
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.
Similar to LaTeX, using $
and $$
to escape inline and display equations also works. However, doing so is deprecated and this functionality may be removed in a future release.
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
Admonitions look like this. This is a !!! note
-type admonition.
Note that admonitions themselves can contain other block-level elements too, such as code blocks. E.g.
f(x) = x^2
However, you can not have at-blocks, docstrings, doctests etc. in an admonition.
Headings are OK though:
Heading 1
Heading 2
Heading 3
Heading 4
Heading 5
Heading 6
Info admonition
This is a !!! info
-type admonition. This is the same as a !!! note
-type.
Tip admonition
This is a !!! tip
-type admonition.
Warning admonition
This is a !!! warning
-type admonition.
Danger admonition
This is a !!! danger
-type admonition.
Compat admonition
This is a !!! compat
-type admonition.
TODO admonition
This is a !!! todo
-type 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>
.
'details' admonition
This is a !!! details
-type admonition.
Unknown admonition class
Admonition with an unknown admonition class. This is a code example
.
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
- Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- Nulla quis venenatis justo.
- 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.
- Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- Nulla quis venenatis justo.
- 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
- Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- Nulla quis venenatis justo.
- In non sodales eros.
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.
- Lorem ipsum dolor sit amet, consectetur adipiscing elit.
- Nulla quis venenatis justo.
- In non sodales eros.
Fusce nec urna eu orci porta blandit.
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
object | implemented | value |
---|---|---|
A | ✓ | 10.00 |
BB | ✓ | 1000000.00 |
With explicit alignment.
object | implemented | value |
---|---|---|
A | ✓ | 10.00 |
BB | ✓ | 1000000.00 |
Tables that are too wide should become scrollable.
object | implemented | value |
---|---|---|
A | ✓ | 10.00 |
BBBBBBBBBBBBBBBBBBBB | ✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓✓ | 1000000000000000000000000000000000000000000000000000000.00 |
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.
Level 1 and 2 heading show up in the sidebar, for the current page.
Note that in docstrings, the headings get rewritten as just bold text right now:
Main.DocumenterShowcase.baz
— Functionbaz(x, f, k)
Function with a more complex docstring. Headings that are part of docstrings are not rendered as headings but rather as bold text:
Arguments
x::Integer
: the first argumentf
: a function with multiple allowable arguments itselfPattern
f(a::Integer)
f(a::Real)
f(a::Real, b::Real)
k::Integer
: the third argument
See also bar
.
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
DocumenterShowcase
— ModuleThis is the DocumenterShowcase
, which contains
This showcase page is included in Documenter version 0.24.0 and above.
Contents
Docstrings can contain admonitions and other block-level nodes.
This admonition is in a docstring. It itself can contain block levels nodes such as code blocks:
println("Hello World")
... or block quotes:
Lorem ipsum.
In fact, while not recommended, you can actually have a matryoshka of admonitions:
Stack overflow.
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
Main.DocumenterShowcase.foo
— Methodfoo(::Integer)
Docstring for foo(::Integer)
.
And now, by having DocumenterShowcase.foo(::AbstractString)
in the @docs
block will give the other docstring
Main.DocumenterShowcase.foo
— Methodfoo(::AbstractString)
Docstring for 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:
Main.DocumenterShowcase.bar
— Functionbar(::Integer)
Docstring for bar(::Integer)
.
bar(::AbstractString)
Docstring for 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
Main.DocumenterShowcase.bar
— Functionbar(::Integer)
Docstring for bar(::Integer)
.
bar(::AbstractString)
Docstring for 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.
Main.DocumenterShowcase.Foo
— TypeThe type definition.
Main.DocumenterShowcase.Foo
— MethodConstructor Foo()
with no arguments.
Main.DocumenterShowcase.Foo
— MethodConstructor Foo{T}()
with one parametric argument.
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".
""")
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.
Color output requires Julia 1.6 or higher. To enable color output pass ansicolor=true
to Documenter.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> x
42
julia> y
ERROR: UndefVarError: `y` not defined
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)