From 0c553920d3f2d88f192117ed4f589abeecdbf876 Mon Sep 17 00:00:00 2001
From: Morten Piibeleht <morten.piibeleht@gmail.com>
Date: Wed, 26 Jun 2024 14:41:25 +1200
Subject: [PATCH] docs: add name block examples to showcase.md (#2539)

---
 docs/src/man/syntax.md |   4 +-
 docs/src/showcase.md   | 150 +++++++++++++++++++++++++++++++++++------
 2 files changed, 130 insertions(+), 24 deletions(-)

diff --git a/docs/src/man/syntax.md b/docs/src/man/syntax.md
index 270d083829..3988fe34e7 100644
--- a/docs/src/man/syntax.md
+++ b/docs/src/man/syntax.md
@@ -393,7 +393,7 @@ As with `@index` if `Pages` is not provided then all pages are included. The def
 
     Documenter will then list the contents of the "Subsection" pages, and they will always appear in the same order as they are in the sidebar.
 
-## `@example` block
+## [`@example` block](@id reference-at-example)
 
 Evaluates the code block and inserts the result of the last expression into the final document along with the
 original source code. If the last expression returns `nothing`, the `stdout`
@@ -689,7 +689,7 @@ Named `@repl <name>` blocks behave in the same way as named `@example <name>` bl
     `for` loops etc. When using Documenter with Julia 1.5 or above, Documenter uses the soft
     scope in `@repl`-blocks and REPL-type doctests.
 
-## `@setup <name>` block
+## [`@setup <name>` block](@id reference-at-setup)
 
 These are similar to `@example` blocks, but both the input and output are hidden from the
 final document. This can be convenient if there are several lines of setup code that need to be
diff --git a/docs/src/showcase.md b/docs/src/showcase.md
index f1e8715e40..34ba1e60f6 100644
--- a/docs/src/showcase.md
+++ b/docs/src/showcase.md
@@ -371,9 +371,57 @@ Script-style doctests are supported too:
 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.
+
+```jldoctest; setup=:(using Documenter)
+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.
+
+````markdown
+```@meta
+DocTestSetup = quote
+  f(x) = x^2
+end
+```
+````
+```@meta
+DocTestSetup = quote
+  f(x) = x^2
+end
+```
+
+```jldoctest
+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`.
+
+````markdown
+```@meta
+DocTestSetup = nothing
+```
+````
+```@meta
+DocTestSetup = nothing
+```
+
+
 ## Running interactive code
 
-[`@example` block](@ref) run a code snippet and insert the output into the document.
+[`@example` block](@ref reference-at-example) run a code snippet and insert the output into the document.
 E.g. the following Markdown
 
 ````markdown
@@ -419,7 +467,7 @@ println("Hello World")
 
 ### Color output
 
-Output from [`@repl` block](@ref)s and [`@example` block](@ref)s support colored output,
+Output from [`@repl` block](@ref)s and [`@example` block](@ref reference-at-example)s support colored output,
 transforming ANSI color codes to HTML.
 
 !!! compat "Julia 1.6"
@@ -499,36 +547,94 @@ median(xs)
 sum(xs)
 ```
 
-## Doctest showcase
+### Named blocks
 
-Currently exists just so that there would be doctests to run in manual pages of Documenter's
-manual. This page does not show up in navigation.
+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.
 
-```jldoctest
-julia> 2 + 2
-4
+````markdown
+```@example block-name
+x = 40
+```
+will show up like this:
+````
+```@example block-name
+x = 40
 ```
 
-The following doctests needs doctestsetup:
+````markdown
+```@example block-name
+x + 1
+```
+will show up like this:
+````
+```@example block-name
+x + 1
+```
 
-```jldoctest; setup=:(using Documenter)
-julia> Documenter.splitexpr(:(Foo.Bar.baz))
-(:(Foo.Bar), :(:baz))
+When you need setup code that you do not wish to show in the generated documentation, you can use [an `@setup` block](@ref reference-at-setup):
+
+````markdown
+```@setup block-name
+x = 42
+```
+````
+```@setup block-name
+x = 42
 ```
 
-Let's also try `@meta` blocks:
+The [`@setup` block](@ref reference-at-setup) essentially acts as a hidden [`@example` block](@ref reference-at-example).
+Any state it sets up, you can access in subsequent blocks with the same name.
+For example, the following `@example` block
 
-```@meta
-DocTestSetup = quote
-  f(x) = x^2
-end
+````markdown
+```@example block-name
+x
 ```
+````
 
-```jldoctest
-julia> f(2)
-4
+will show up like this:
+
+```@example block-name
+x
 ```
 
-```@meta
-DocTestSetup = nothing
+You also have continued blocks which do not evaluate immediately.
+
+````markdown
+```@example block-name; continued = true
+y = 99
+```
+````
+```@example block-name; continued = true
+y = 99
+```
+
+The continued evaluation only applies to [`@example` blocks](@ref reference-at-example) 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.
+
+````markdown
+```@repl block-name
+x
+y
+```
+````
+
+```@repl block-name
+x
+y
+```
+
+Another [`@example` block](@ref reference-at-example) with the same name will, however, finish evaluating it.
+So a block like
+
+````markdown
+```@example block-name
+(x, y)
+```
+````
+
+will lead to
+
+```@example block-name
+(x, y)
 ```