jldoctest: add some missing end markers

[benlorenz]

x-ref: #2077 (comment)

[fingolfin]

Thanks!

[benlorenz]

If someone wants to repeat this the following code might help. I think it is somewhat fragile to add this to the CI and with less than 10 such cases in Oscar + all cornerstones in total it doesn't seem that big of an issue.

An alternative but very crude check is running grep -lr '```jldoctest' on the documentation html files (e.g. dev directory in the gh-pages branch) but it is somewhat annoying to find the corresponding source.

Julia code

This is totally unoptimized and takes about 15 seconds.

using Markdown

# this might not catch all broken jldoctests but seems to work for now
function has_broken_doctest(md::Markdown.MD)
   todo = copy(md.content)
   while !isempty(todo)
      elem = popfirst!(todo)
      # nested
      if elem isa Markdown.MD
         append!(todo, elem.content)
      else
         # proper docstrings are in a Markdown.Code block
         if elem isa Markdown.Paragraph
            for block in elem.content
               # unterminated jldoctests seem to end up inside some string in a Paragraph block
               if contains(string(block),"```jldoctest")
                  return true
               end
            end
         end
      end
   end
   return false
end

function find_docstr_src(docs)
   locs = []
   res = docs.meta[:results]
   for i in 1:length(docs.content)
      if has_broken_doctest(docs.content[i])
         file = res[i].data[:path]
         line = res[i].data[:linenumber]
         push!(locs, (file,line))
      end
   end
   return locs
end

function get_broken_docstrings(m::Module)
   allpairs = collect(zip(Iterators.repeated(m), names(m; all=true, imported=false)));
   broken = []
   locs = []
   done = [m]

   while !isempty(allpairs)
      (src, name) = popfirst!(allpairs)
      memberobj = try 
               getfield(src,name)
            catch
               nothing
            end
      if memberobj isa Module
         if !(memberobj in done)
            push!(done, memberobj)
            # we only want to consider one pkg
            # but note that we still seem to pick up some reexported names
            # even though imported=false and the check below
            if (pkgdir(memberobj) == pkgdir(m))
               newnames = names(memberobj; all=true, imported=false)
               filter!(x->!((memberobj, x) in allpairs || x in done), newnames)
               append!(allpairs, collect(zip(Iterators.repeated(memberobj), newnames)))
            end
         end
      elseif !isnothing(memberobj)
         docs = Base.Docs.doc(memberobj)
         if docs isa Markdown.MD && has_broken_doctest(docs)
            if !(memberobj in broken)
               loc = find_docstr_src(docs)
               push!(broken, memberobj)
               # we could filter out docs from other packages via startswith(x, pkgdir(m))
               append!(locs,loc)
            end
         end
      end
   end
   return locs
end