Documentation: Explain how to execute the doctests

[HereAround]

Oscar.build_doc() does not execute the doc_tests. So as a humble user or developer, one might wonder "how do I execute the doc tests locally to test my code?". Unless I am mistaken, the documentation for this question is rather sparse. Here are a couple of suggestions from communication with @thofma.

One can provide additional arguments to Oscar.build_doc() so that the doctests are being executed:

• build_doc(; doctest = true),
• build_doc(; doctest = true, strict = true).

In the past, I used to directly execute the make.jl file in the docs folder. I recently noticed that this triggered a lot of failures. As @thofma explained to me, the output format/ordering of output is different in julia 1.6 and 1.7. OSCAR sticks to the standard of the LTS 1.6 while I was using 1.7 locally. Maybe also worth mentioning towards documentation?

And of course, there are options that can be used for a direct execution of the make.jl in the docs folder. @thofma suggested the following:

• julia --project=. make.jl
• Probably also julia --project=. -e 'using Pkg; Pkg.instantiate() before.

[fingolfin]

Regarding tests: This should be covered by the developer docs. A minimal start is here: https://oscar-system.github.io/Oscar.jl/dev/DeveloperDocumentation/documentation/#Automatically-repairing-jldoctests -- but of course not enough. IMHO there should be a separate section on "Tests", and in addition to what you mention, it should also discuss Oscar.test_module.

Regarding make.jl: I don't think executing this "directly in the docs folder" is a good idea, and we should not recommend that.

We definitely should state that Julia 1.6 is the reference for doctests, at the very place in the section of the dev docs I just linked to, but of course can also be mentioned in further places.

[lkastner]

I dealt with some of these in the PR above. Nevertheless this will stay a recurring issues, since people don't read documentation.

Is there a reason that build_doc and test_module don't have docstrings? From the Julia terminal the names don't seem to be taken, so that could be a viable option.

[fingolfin]

I dealt with some of these in the PR above. Nevertheless this will stay a recurring issues, since people don't read documentation.

Is there a reason that build_doc and test_module don't have docstrings? From the Julia terminal the names don't seem to be taken, so that could be a viable option.

I can't think of a reason, other than "nobody did it yet". Sounds like a good idea to me!

[lkastner]

I can't think of a reason, other than "nobody did it yet". Sounds like a good idea to me!

Ok, I'll make a PR with that and restructure a little. Probably won't be perfect, but should solve this issue.