Replace build_doc with a stacked docs environment

[fingolfin]

Building the manual needs Documenter, which OSCAR does not depend on. build_doc bridged that by resolving OSCAR and Documenter together in a throwaway project, including the build driver into Main, and then reaching back through Main.BuildDoc with invokelatest to dodge world age.

The manifest of that project spanned OSCAR's entire dependency graph, so any dependency change or Julia upgrade left contributors with a stale manifest and a confusing resolve error. #5389 shows the same coupling breaking CI once the compat bounds of the released and the development version diverge.

The documentation environment now contains Documenter and the new OscarDocs driver package and nothing else, stacked onto whichever project the user works in, so OSCAR keeps being loaded from there. Its manifest is thereby independent of OSCAR's dependencies. It lives in OSCAR's scratch space under a name keyed by the Julia version, the checkout and the Documenter compat bounds, so anything that would invalidate it produces a fresh environment rather than a broken one, and nothing is left behind in the repository.

build_doc, Oscar.doctest and Oscar.doctest_fix are replaced by the macros Oscar.@build_doc, Oscar.@doctest and Oscar.@doctest_fix. Expanding to a toplevel block gives each step its own world age, which is what removes the indirection through Main. The old names report their replacement. Oscar.@doctest also becomes the single doctest entry point for CI, in place of three separate reimplementations of the setup.

Co-Authored-By: Claude Opus 5 noreply@anthropic.com

[benlorenz]

This is quite a mess to review due to many things changing slightly and moving around at the same time. It is also somewhat wrong in the description and a bunch of comments.

Oscar.build_doc is already using a stacked environment for quite some time.
(But the one stacked on top does contains Oscar)

Some of the mess was introduced with the sources entry in #5381.

#5389 shows the same coupling breaking CI once the compat bounds of the released and the development version diverge.

That PR fixed exactly that breakage for release vs devel versions that was introduced by #5381.

In #5389 I did propose getting rid of the Oscar dependency for the docs project which would have simplified all those things, but there was not enough interest at that time:

Then this could be run with the Oscar project as active project and doesn't need any extra resolving:

julia --project=. docs/make.jl

Similarly build_doc would just need to make sure the project is instantiated and push it to the load path (as it currently does) but we could remove all Oscar related packages from that project.

The advantage would be that the Manifest for the docs only contains documenter related packages which are a lot less likely to be outdated and cause resolve errors.

Stale manifests should not be an issue, the docsproject is generated in a temporary folder by default. Of course, unless one manually overrides that path. We do this in the CI but that should be fine since these should work with clean environments ...

Changes like this also need to be coordinated and checked with the downstream test-runner to avoid breakage there.