Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Rewrite manual examples to use jldoctest and fix them as needed #1683

Open
fingolfin opened this issue Feb 22, 2024 · 0 comments
Open

Rewrite manual examples to use jldoctest and fix them as needed #1683

fingolfin opened this issue Feb 22, 2024 · 0 comments
Labels
doc This change adds or pertains to documentation

Comments

@fingolfin
Copy link
Member

fingolfin commented Feb 22, 2024

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 fingolfin added the doc This change adds or pertains to documentation label Feb 22, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
doc This change adds or pertains to documentation
Projects
None yet
Development

No branches or pull requests

1 participant