docs: collapsed example

.github/workflows/docs.yml

@@ -16,7 +16,12 @@ jobs:
         with:
           version: '1.7'
       - name: Install dependencies
-        run: julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
+        run: julia --project=docs/ -e '
+          using Pkg
+          # Add a 1.0.0-DEV version of Documenter: https://github.com/JuliaDocs/Documenter.jl/commit/89e77c23bb3c5f55f50e3b2d48fc57e9bf6c9d7d
+          Pkg.add(url="https://github.com/JuliaDocs/Documenter.jl', rev="89e77c23bb3c5f55f50e3b2d48fc57e9bf6c9d7d")
+          Pkg.develop(PackageSpec(path=pwd()))
+          Pkg.instantiate()'
       - name: Build and deploy
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} # For authentication with GitHub Actions token

docs/ext/DocumenterCollapsedExample.jl

@@ -0,0 +1,51 @@
+"""
+Documenter extension module, providing a collapsed example block with code evalulation.
+"""
+module DocumenterCollapsedExample
+
+import Documenter
+using Documenter: MarkdownAST, DOM
+using Documenter.HTMLWriter: DCtx
+using Documenter.MarkdownAST: Node
+
+# This digs deep into Documenter internals, by defining a new at-block that gets evaluated
+# during the Documenter "expansion" step. The expansion of CollapsedExample re-uses the
+# standard runner for @example blocks, but creates a custom MarkdownAST block, which then
+# is dispatched on in the HTMLWriter (domify).
+abstract type CollapsedExample <: Documenter.Expanders.ExpanderPipeline end
+Documenter.Selectors.matcher(::Type{CollapsedExample}, node, page, doc) = Documenter.Expanders.iscode(node, "@collapsed-example")
+Documenter.Selectors.order(::Type{CollapsedExample}) = 7.9
+function Documenter.Selectors.runner(::Type{CollapsedExample}, node, page, doc)
+    # The ExampleBlocks runner will fail, unless the code block language is `@example *`,
+    # so we override it here.
+    node.element.info = "@example"
+    Documenter.Selectors.runner(Documenter.Expanders.ExampleBlocks, node, page, doc)
+    # Runner will set node.elements to be Documenter.MultiOutput, which we will replace
+    # with CollapsedOutput.
+    node.element = CollapsedOutput(node.element.codeblock)
+    return
+end
+# This is the MarkdownAST element that replaces Documenter.MultiOutput so that we could
+# dispatch on it in the writer.
+struct CollapsedOutput <: Documenter.AbstractDocumenterBlock
+    codeblock :: MarkdownAST.CodeBlock
+end
+function Documenter.HTMLWriter.domify(dctx::DCtx, node::Node, ::CollapsedOutput)
+    DOM.@tags details summary
+    # Documenter.MultiOutput has two types of children nodes: MarkdownAST.CodeBlock
+    # is assumed to be the input code block (which gets surrounded by `<details>`),
+    # and others should be Documenter.MultiOutputElement, which are the ouputs.
+    # We'll use the standard domify() methods for the latter.
+    map(node.children) do node
+        if node.element isa MarkdownAST.CodeBlock
+            details[:style=>"padding: 0rem; border: 0px solid lightgray; color: gray"](
+                summary("See code"),
+                Documenter.HTMLWriter.domify(dctx, node)
+            )
+        else
+            Documenter.HTMLWriter.domify(dctx, node)
+        end
+    end
+end
+
+end # module

docs/make.jl

@@ -2,6 +2,14 @@ ENV["GKSwstype"] = 322 # workaround for gr segfault on GH actions
 # ENV["GKS_WSTYPE"]=100 # try this if above does not work
 using Documenter, RobustAndOptimalControl, ControlSystemsBase
 
+# Make it possible to load the CollapsedExample Documenter extension
+let exts = joinpath(@__DIR__, "ext")
+      if !(exts in LOAD_PATH)
+            pushfirst!(LOAD_PATH, exts)
+      end
+end
+import DocumenterCollapsedExample
+
 using Plots
 gr()
 

docs/src/index.md

@@ -14,6 +14,10 @@
 # RobustAndOptimalControl.jl
 This package is an extension to [ControlSystems.jl](https://github.com/JuliaControl/ControlSystems.jl) that provides methods for robust and optimal analysis and synthesis of linear control systems.
 
+```@collapsed-example
+2+2
+```
+
 ## Robust control