Writing jldoctests

This page describes how to write and maintain jldoctest blocks in the documentation. Following these guidelines helps keep doctests reliable and easy to read.

Filters

Use filter = whenever output contains text that might vary across runs. The following are common situations where this may happen:

The output contains arrays with undefined memory (e.g. from undef or similar)
The output contains random numbers
The output contains timing information
The output contains file system paths

Common filter sequences

The documentation relies on several recurring patterns:

r"int.jl:\\d+" — remove line numbers from introspection macros.
r"Stacktrace:(\\n \\[0-9]+\\].*)*" — hide stack traces when illustrating errors.
r"Closest candidates.*\\n .*" — skip the method suggestions printed by MethodError.
r"@ .*" — strip file locations from the output of methods or @which.
r"\\@world\\(MyStruct, \\d+:\\d+\\)" — filter world age numbers.
r"with \\d+ methods" — ignore method counts when redefining functions.
r"[0-9\\.]+ seconds \\(.*?\\)" — remove timing output with memory information.
r"[0-9\\.]+ seconds" — remove simple timing results.
r"[0-9\\.]+" — filter digits from names such as anonymous functions.
r"([A-B] [0-5])" and r"[A-B] [X-Z] [0-5]" — account for non-deterministic process output.
r"(world\\nhello|hello\\nworld)" — allow either ordering of interleaved output.

If none of these match your situation, craft a regular expression that removes the varying text. Using filters keeps doctests stable across platforms and Julia versions.

Double escaping in docstrings

When writing regex filters inside docstrings, remember to double escape backslashes. For example, use r"[\\d\\.]+" instead of r"[\d\.]+". This is necessary because the docstring itself processes escape sequences before the regex is created.

Setup code

Small setup expressions may be placed inline using the setup = option:

```jldoctest; setup = :(using InteractiveUtils)
...
```

For longer setup code or if multiple blocks require the same environment, use the DocTestSetup meta block:

```@meta
DocTestSetup = :(import Random; Random.seed!(1234))
```

and disable it afterwards with

```@meta
DocTestSetup = nothing
```

Teardown code

If you need teardown code (e.g. to delete created temporary files or to reset the current directory), you can use the teardown = option:

```jldoctest; setup = :(oldpath = pwd(); cd(mktempdir())), teardown = :(cd(oldpath))
...
```

Maintaining state between snippets

Related doctest blocks can share state by giving them the same label after the jldoctest keyword. The manual uses this pattern to demonstrate mutation:

```jldoctest mutation_vs_rebind
julia> a = [1,2,3]
...
```

and later

```jldoctest mutation_vs_rebind
julia> a[1] = 42
...
```

Blocks with the same name execute sequentially during doctesting, so variables created in the first block remain available in the following ones.

When a snippet needs to preserve its result for later examples, give it a label and reuse that label. This avoids repeating setup code and mirrors a REPL session more closely.

Syntax versioning

When documenting features that use new Julia syntax, you can specify the required syntax version for a doctest block using the syntax = option:

```jldoctest; syntax = v"1.14"
julia> result = @label myblock begin
           for i in 1:10
               i > 5 && break myblock i * 2
           end
           0
       end
12
```

This ensures the code block is parsed using the specified Julia syntax version, allowing doctests for new language features to pass even when the documentation is built with an older default syntax.

For modules that predominantly use new syntax, you can set a global default using DocTestSyntax in a meta block:

```@meta
DocTestSyntax = v"1.14"
```

Per-block syntax = settings override the global DocTestSyntax setting.

Julia 1.14

Syntax versioning for doctests requires Julia 1.14 or later. When running doctests on older Julia versions, blocks with syntax = v"1.14" or higher will be skipped with a warning.