Allow specifying a global default for @meta block settings

[fingolfin]

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.

Resolves #2512. Resolves #2684. Resolves #1253

CC @lgoettgens

---

This is a first prototype. No documentation or changelog entry yet as the design is still not finalized.

This adds a new kwarg default_meta to makedocs -- contrary to the discussion in #2512 this expects a Dict{Symbol,Any}. The main reasons for doing it this way are:

1. this was the easiest to implement :-) which is important for an MVP
2. arguably this is also the easiest to document and explain (as in: what are the semantics of this option)
3. it is sufficient to set up a basic test, and also sufficient for my primary applications in Oscar.jl
4. it does not preclude us from accepting a quoted code block in the future -- we could simply add support for that in addition to what this PR implements...

I've been wondering if it wouldn't be nicer to accept a named tuple instead of (or in addition to?) a Dict{Symbol,Any}, the syntax then would look a bit closer to the actual content of a @meta block.

Of course accepting actual quoted code blocks would make the input even closer to an actual @meta block. As I wrote above, we could still add support for that if it turns out someone needs it. When we do, it then should also be easier to resolve the question "when to evaluate the code block" (once at the start? once for each page? something else?) because we'll have a concrete usecase at hand...

That said, I am totally open to change this MVP based on your comments.

[fingolfin]

I am happy with this now. Any thought, @lgoettgens @mortenpi ?

[mortenpi]

Just bikeshedding this here. I was thinking maybe it could be page_meta or even just meta.

So, currently, this will only affect the Markdown pages, and for docstrings you'd still have to do setdocmeta!, right? I am now wondering if this should also apply to docstrings (with setdocmeta! providing a per-module override still).

Do you have any sense if the global at-meta stuff you'd like to apply for pages would also be useful for docstrings? Are they usually basically the same in your experience?

[fingolfin]

We use the same DocTestSetup in @meta blocks in every .md file and also set it via setdocmeta!. I believe they would be basically the same, and having default_meta/page_meta/meta also set a default for doctests inside docstrings would then unify 2 of 3 places where in my experience one needs to set these

So it'd help! But maybe not quite enough, at least if one also wants to run doctests outside of building the documentation. We do that (via an explicit doctest(MyPackage) call in our CI) in order to get code coverage.

For details see also my comment #2126 (comment)

[mortenpi]

it does not preclude us from accepting a quoted code block in the future -- we could simply add support for that in addition to what this PR implements...

I'm happy if it's a Dict. The argument that we can always expand it in the future is convincing. Could even add a code comment to that effect somewhere, that we may want to expand it in the future.

[fingolfin]

Just to say, one could also allow (instead or in addition) named tuples:

Suggested change

	default_meta = Dict(:DocTestSetup => :(x = 42))
	default_meta = (DocTestSetup = :(x = 42), )

OK that's a bit awkward in the single argument list. But it is a tad closer to how the content of the @meta blocks look (no : in front of names, = instead of =>)

Anyway I am totally fine either way, just wanted to bring it up

[fingolfin]

I've resolved the TODOs and renamed default_meta to meta as suggested. From my point of view this is ready for review.