Nemo.jl icon indicating copy to clipboard operation
Nemo.jl copied to clipboard

Rewrite manual examples to use `jldoctest` and fix them as needed

Open fingolfin opened this issue 4 months ago • 0 comments

Motivated by PR #1682 -- we have broken examples in the manual and nothing notifies us about that.

Consider an example like this in the manual:

```julia
RR = RealField()
T, z = polynomial_ring(RR, "z")
   
h = z^2 + 2z + 1

s, t = evaluate2(h, RR("2.0 +/- 0.1"))
```

it should be rewritten to use a jldoctest, like this:

```jldoctest
julia> RR = RealField()
Real field

julia> T, z = polynomial_ring(RR, "z")
(Univariate polynomial ring in z over RR, z)

julia> h = z^2 + 2z + 1
z^2 + 2.000000000000000000000000000000*z + 1

julia> s, t = evaluate2(h, RR("2.0 +/- 0.1"))
([9e+0 +/- 0.611], [6e+0 +/- 0.201])
```

Overall, all remaining examples involving julia blocks should be rewritten to use jldoctest instead.

Two strategies to deal with that:

  1. Manual processing:
    • Go manually over each julia block, copy & paste the code into a Julia REPL session
    • then change julia to jldoctest
    • finally copy & paste what you got back in the REPL into the example block
    • repeat as often as needed / your patience lasts
    • commit everything
    • then "post process" the result by editing docs/make.jl, changing doctest = true to doctest = :fix; then run docs/make.jl to let it "clean up" those doctests for you (I guess this also needs an explanation.... perhaps it will be more efficient if we add a little helper script to the repository that does all of that automatically...)
  2. Alternative strategy which one could also semi-automate by writing a little helper script:
    • change julia to jldoctest
    • add prefix julia> to each code line in the example input, make sure each code line is separated by at least one empty line
    • repeat this for as many blocks as you want (I've done this in the past for all blocks in a file via some basic scripting
    • save & commit the result,
    • perform the same "doctest = :fix" dance as described above.

Of course in each case at some point you'll run into examples that just produce an error, and which then need to be fixed. How to fix them is not always trivial, and may require asking here for advice.

E.g. one such error is already being discussed in issue #1388.

To find otheres, one can search for occurrences of ArbFieldElem in docs/ outside of arb.md, often nearby there are broken examples, e.g. in polynomial.md:

RR = RealField()
R, x = polynomial_ring(RR, "x")

xs = ArbFieldElem[inv(RR(i)) for i=1:5]
f = from_roots(R, xs)

Here the simple fix is to drop the ArbFieldElem.

But others won't be as simple to fix.

fingolfin avatar Feb 22 '24 10:02 fingolfin