Run CI on experimental *.md doc files (#4083)

* Move linking of experimental docs to separate function

* Refactor `link_experimental_docs`

* Clean up

* Only delete "wrong" symlinks

* Move `walkdir` hack in another file

* Fix doctests

docs/documenter_helpers.jl

@@ -23,3 +23,11 @@ else
     end
   end
 end
+
+# We monkey-patch Base.walkdir to use true as default value for follow_symlinks
+# (normally false is the default), in order to "trick" the Documenter code into
+# following those symlinks.
+# See also:
+# https://github.com/JuliaDocs/Documenter.jl/pull/552
+# https://github.com/JuliaLang/julia/blob/master/doc/make.jl#L19
+Base.walkdir(str::String) = Base.walkdir(str; follow_symlinks=true)

docs/make_work.jl

@@ -26,14 +26,6 @@ include("citation_style.jl")
 # Remove the module prefix
 Base.print(io::IO, b::Base.Docs.Binding) = print(io, b.var)
 
-# We monkey-patch Base.walkdir to use true as default value for follow_symlinks
-# (normally false is the default), in order to "trick" the Documenter code into
-# following those symlinks.
-# See also:
-# https://github.com/JuliaDocs/Documenter.jl/pull/552
-# https://github.com/JuliaLang/julia/blob/master/doc/make.jl#L19
-Base.walkdir(str::String) = Base.walkdir(str; follow_symlinks=true)
-
 # When we read a `doc.main` from an experimental package, we need to equip all
 # its entries with a prefix to fit with our docs. The doc.main of an
 # experimental package will contain paths relative to
@@ -83,22 +75,13 @@ function setup_experimental_package(Oscar::Module, package_name::String)
     return []
   end
 
-  # Set symlink inside docs/src/experimental
-  symlink_link = joinpath(Oscar.oscardir, "docs/src/Experimental", package_name)
-  symlink_target = joinpath(Oscar.oscardir, "experimental", package_name, "docs", "src")
-
-  if !ispath(symlink_target)
+  # Assumes that a symbolic link from `experimental/package_name/docs/src`
+  # to `docs/src/Experimental/package_name` has been created (or there is no
+  # documentation for this package)
+  if !ispath(joinpath(Oscar.oscardir, "docs/src/Experimental", package_name))
     return []
   end
 
-  if !ispath(symlink_link)
-    symlink(symlink_target, symlink_link)
-  elseif !islink(symlink_link) || readlink(symlink_link) != symlink_target
-    error("""$symlink_link already exists, but is not a symlink to $symlink_target
-    Please investigate the contents of $symlink_link,
-    optionally move them somewhere else and delete the directory once you are done.""")
-  end
-
   # Read doc.main of package
   exp_s = read(doc_main_path, String)
   exp_doc = eval(Meta.parse(exp_s))
@@ -116,15 +99,12 @@ function doit(
   doctest::Union{Bool,Symbol}=true,
 )
 
-  # Remove symbolic links from earlier runs
-  expdocdir = joinpath(Oscar.oscardir, "docs", "src", "Experimental")
-  for x in readdir(expdocdir; join=true)
-    islink(x) && rm(x)
-  end
-
   # include the list of pages, performing substitutions
   s = read(joinpath(Oscar.oscardir, "docs", "doc.main"), String)
   doc = eval(Meta.parse(s))
+
+  # Link experimental docs to `docs/src` and collect the documentation pages
+  Oscar.link_experimental_docs()
   collected = Any["Experimental/intro.md"]
   for pkg in Oscar.exppkgs
     pkgdocs = setup_experimental_package(Oscar, pkg)

experimental/IntersectionTheory/docs/src/AbstractVarieties.md

@@ -1,5 +1,6 @@
 ```@meta
 CurrentModule = Oscar
+DocTestSetup = Oscar.doctestsetup()
 ```
 
 # Abstract Varieties

experimental/IntersectionTheory/docs/src/examples.md

@@ -43,7 +43,7 @@ julia> Z = dual(tautological_bundles(PF)[1])
 AbstractBundle of rank 1 on AbstractVariety of dim 8
 
 julia> z = chern_class(Z, 1)
-h
+z
 
 julia> integral((2*p + z)^8)
 92

experimental/MatroidRealizationSpaces/docs/src/introduction.md

@@ -1,5 +1,6 @@
 ```@meta
 CurrentModule = Oscar
+DocTestSetup = Oscar.doctestsetup()
 ```
 
 # Matroid Realization Spaces
@@ -68,8 +69,7 @@ Blowup
 with domain
   scheme over QQ covered with 2 patches
     1a: [(s1//s0), x1, x2]   scheme(-(s1//s0)*x1 + 4*(s1//s0) + x2^2 - 8) \ scheme((x1 - x2)*x2*x1*(x2 - 1)*(x1 - 1)*(x1 + x2^2 - x2)*(x1*x2 - x1 - x2^2))
-    2a: [(s0//s1), x2]       scheme(0) \ scheme(((s0//s1)*x2^2 - 8*(s0//s1) - x2 + 4)*x2*((s0//s1)*x2^2 - 8*(s0//s1) + 4)*(x2 - 1)*((s0//s1)*x2^2 - 8*(s0//s1) + 3)*((s0//s1)*x2^2 - 8*(s0//s1) + x2^2 - x2 + 4)*((
-    s0//s1)*x2^3 - (s0//s1)*x2^2 - 8*(s0//s1)*x2 + 8*(s0//s1) - x2^2 + 4*x2 - 4))
+    2a: [(s0//s1), x2]       scheme(0) \ scheme(((s0//s1)*x2^2 - 8*(s0//s1) - x2 + 4)*x2*((s0//s1)*x2^2 - 8*(s0//s1) + 4)*(x2 - 1)*((s0//s1)*x2^2 - 8*(s0//s1) + 3)*((s0//s1)*x2^2 - 8*(s0//s1) + x2^2 - x2 + 4)*((s0//s1)*x2^3 - (s0//s1)*x2^2 - 8*(s0//s1)*x2 + 8*(s0//s1) - x2^2 + 4*x2 - 4))
 and exceptional divisor
   effective cartier divisor defined by
     sheaf of ideals with restrictions

src/utils/docs.jl

@@ -14,7 +14,10 @@
 
 # Oscar needs some complicated setup to get the printing right. This provides a
 # helper function to set this up consistently.
-doctestsetup() = :(using Oscar; Oscar.AbstractAlgebra.set_current_module(@__MODULE__))
+function doctestsetup()
+  link_experimental_docs()
+  return :(using Oscar; Oscar.AbstractAlgebra.set_current_module(@__MODULE__))
+end
 
 # use tempdir by default to ensure a clean manifest (and avoid modifying the project)
 function doc_init(;path=mktempdir())
@@ -231,3 +234,38 @@ function build_doc(; doctest::Union{Symbol, Bool} = false, warnonly = true, open
     @warn versionwarn
   end
 end
+
+# Create symbolic links from any documentation directory in `experimental` into
+# `docs/src`
+function link_experimental_docs()
+  # Remove symbolic links from earlier runs
+  expdocdir = joinpath(oscardir, "docs", "src", "Experimental")
+  for x in readdir(expdocdir; join=true)
+    !islink(x) && continue
+    pkg = splitpath(x)[end]
+    if !(pkg in exppkgs)
+      # We don't know this link, let's remove it
+      rm(x)
+    end
+  end
+
+  for pkg in exppkgs
+    # Set symlink inside docs/src/experimental
+    symlink_link = joinpath(oscardir, "docs/src/Experimental", pkg)
+    symlink_target = joinpath(oscardir, "experimental", pkg, "docs", "src")
+
+    if !ispath(symlink_target)
+      continue
+    end
+
+    if !ispath(symlink_link)
+      symlink(symlink_target, symlink_link)
+    elseif !islink(symlink_link) || readlink(symlink_link) != symlink_target
+      error("""$symlink_link already exists, but is not a symlink to $symlink_target
+      Please investigate the contents of $symlink_link,
+      optionally move them somewhere else and delete the directory once you are done.""")
+    end
+  end
+
+  return nothing
+end