Allow specifying a global default for @meta block settings

This allows to e.g. use a common doctest setup block on all pages,
thus complementing `DocMeta.setdocmeta!`.

Other nice applications include changing certain settings,
such `CollapsedDocStrings = true` globally, or being able to
specify `CurrentModule = YourPackageModule` globally.

Author: fingolfin

src/doctests.jl

@@ -14,7 +14,7 @@ struct DocTestContext
     file::String
     doc::Documenter.Document
     meta::Dict{Symbol, Any}
-    DocTestContext(file::String, doc::Documenter.Document) = new(file, doc, Dict())
+    DocTestContext(file::String, doc::Documenter.Document) = new(file, doc, copy(doc.user.default_meta))
 end
 
 """

src/documents.jl

@@ -341,6 +341,7 @@ struct User
     version::String # version string used in the version selector by default
     highlightsig::Bool  # assume leading unlabeled code blocks in docstrings to be Julia.
     draft::Bool
+    default_meta::Dict{Symbol, Any} # default @meta block data for pages
 end
 
 """
@@ -403,6 +404,7 @@ function Document(;
         version::AbstractString = "",
         highlightsig::Bool = true,
         draft::Bool = false,
+        default_meta::Dict{Symbol, Any} = Dict{Symbol, Any}(),
         others...
     )
 
@@ -468,6 +470,7 @@ function Document(;
         version,
         highlightsig,
         draft,
+        default_meta,
     )
     internal = Internal(
         assetsdir(),

src/expander_pipeline.jl

@@ -52,7 +52,7 @@ function expand(doc::Documenter.Document)
     for src in Iterators.flatten([priority_pages, normal_pages])
         page = doc.blueprint.pages[src]
         @debug "Running ExpanderPipeline on $src"
-        empty!(page.globals.meta)
+        copy!(page.globals.meta, doc.user.default_meta)
         # We need to collect the child nodes here because we will end up changing the structure
         # of the tree in some cases.
         for node in collect(page.mdast.children)

src/makedocs.jl

@@ -166,6 +166,8 @@ For example, if you have `foo.md` and `bar.md`, `bar.md` would normally be evalu
 Evaluation order among the `expandfirst` pages is according to the order they appear in the
 argument.
 
+**`default_meta`** can be set to TODO. TODO default `@meta` block. TODO
+
 **`draft`** can be set to `true` to build a draft version of the document. In draft mode
 some potentially time-consuming steps are skipped (e.g. running `@example` blocks), which is
 useful when iterating on the documentation. This setting can also be configured per-page

test/default_meta/src/index.md

@@ -0,0 +1,8 @@
+# Testing
+
+We set the `default_meta` feature by having it setting `DocTestSetup`.
+
+```jldoctest
+julia> x
+42
+```

test/default_meta/tests.jl

@@ -0,0 +1,14 @@
+using Documenter
+using Test
+
+const pages = [
+    "Home" => "index.md",
+]
+
+makedocs(sitename = "Test", pages = pages, doctest = true,
+    default_meta = Dict{Symbol,Any}(:DocTestSetup => :(x = 42)))
+# TODO: allow NamedTuples instead or in addition?
+#    makedocs(sitename = "Test", pages = pages, doctest = true,
+#      default_meta = (DocTestSetup => :(x = 42), ))
+
+# the test is passing the doctest

test/runtests.jl

@@ -98,6 +98,10 @@ end
     @info "Building clear_module/tests.jl"
     @quietly include("clear_module/tests.jl")
 
+    # A simple build verifying that default_meta for pages works
+    @info "Building default_meta/tests.jl"
+    @quietly include("default_meta/tests.jl")
+
     # Passing a writer positionally (https://github.com/JuliaDocs/Documenter.jl/issues/1046)
     @test_throws MethodError makedocs(sitename = "", HTML())