Nemo.jl
Nemo.jl copied to clipboard
Rewrite manual examples to use `jldoctest` and fix them as needed
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:
- Manual processing:
- Go manually over each
julia
block, copy & paste the code into a Julia REPL session - then change
julia
tojldoctest
- 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
, changingdoctest = true
todoctest = :fix
; then rundocs/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...)
- Go manually over each
- Alternative strategy which one could also semi-automate by writing a little helper script:
- change
julia
tojldoctest
- 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.
- change
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.