Rewrite manual examples to use jldoctest
and fix them as needed
#1683
Labels
doc
This change adds or pertains to documentation
jldoctest
and fix them as needed
#1683
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:
it should be rewritten to use a
jldoctest
, like this:Overall, all remaining examples involving
julia
blocks should be rewritten to usejldoctest
instead.Two strategies to deal with that:
julia
block, copy & paste the code into a Julia REPL sessionjulia
tojldoctest
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...)julia
tojldoctest
julia>
to each code line in the example input, make sure each code line is separated by at least one empty lineOf 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
indocs/
outside ofarb.md
, often nearby there are broken examples, e.g. inpolynomial.md
:Here the simple fix is to drop the
ArbFieldElem
.But others won't be as simple to fix.
The text was updated successfully, but these errors were encountered: