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