Julia: Doctest ALL the things

[KristofferC]

This is a list of all files that need doctests in the manual. If you have a PR in progress to doctest a file please claim it here. This is in order for people not to do double work. If there is a file that you know of that is fully doctests, please mention it as well.

• [x] Introduction] - @fredrikekre #20183
• [x] Getting Started - @fredrikekre #20183
• [x] Variables - @fredrikekre #20183
• [x] Integers and Floating-Point Numbers - @fredrikekre #20183
• [x] Mathematical Operations and Elementary Functions - @fredrikekre #20183
• [x] Complex and Rational Numbers - @fredrikekre #20183
• [x] Strings - @fredrikekre #20183
• [x] Functions - @fredrikekre #20201
• [x] Control Flow - @fredrikekre #20202
• [x] Scope of Variables - @fredrikekre #20202
• [x] Types - @fredrikekre #20224
• [x] Methods - @fredrikekre #20224
• [x] Constructors - @kshyatt #20285
• [ ] Conversion and Promotion - @kshyatt #20297
• [x] Interfaces - @fredrikekre #20287
• [x] Modules - Nothing runnable
• [x] Documentation - no doctests but some updates: @kristofferc #20442
• [x] Metaprogramming - @kristofferc #20302
• [x] Multi-dimensional Arrays - #20125
• [x] Linear algebra -
• [x] Networking and Streams - @kristofferc #20304
• [x] Parallel Computing -
• [x] Date and DateTime - @kristofferc #20275
• [x] Running External Programs - @fredrikekre #20315
• [x] Calling C and Fortran Code - @kristofferc #20440
• [x] Handling Operating System Variation - No runnable examples
• [x] Interacting With Julia - @fredrikekre
• [x] Embedding Julia - Not doctestable
• [x] Packages - Not so many doctests here but examples should be run through and output updated
• [x] Package Development -
• [x] Profiling -
• [x] Stack Traces -
• [x] Performance Tips - @kristofferc #20312
• [x] Workflow Tips -
• [x] Style Guide - @fredrikekre
• [x] Frequently Asked Questions - @kristofferc #20291
• [x] Noteworthy Differences from other Languages - Doees not contain any examples
• [x] Unicode Input - Does not contain any examples

cc @fredrikekre.

[fredrikekre]

https://github.com/JuliaLang/julia/pull/20183 covers:

• [x] Introduction
• [x] Getting Started
• [x] Variables
• [x] Integers and Floating-Point Numbers
• [x] Mathematical Operations and Elementary Functions
• [x] Complex and Rational Number
• [x] Strings

https://github.com/JuliaLang/julia/pull/20201 covers:

• [x] Functions

https://github.com/JuliaLang/julia/pull/20202 covers:

• [x] Control Flow
• [x] Scope of Variables

https://github.com/JuliaLang/julia/pull/20224 covers:

• [x] Types
• [x] Methods

[kshyatt]

The Linear Algebra section of the manual is already doctested, in #19733

[fredrikekre]

https://github.com/JuliaLang/julia/pull/20125 was Multidimensional Arrays

[kshyatt]

Note that many of these files could certainly use more doctested examples, even if the conversion of existing ones is complete!

[KristofferC]

Yeah that is always the case. This issue is mostly to make sure the current stuff is correct.

[fredrikekre]

Interfaces: https://github.com/JuliaLang/julia/pull/20287

[fredrikekre]

https://github.com/JuliaLang/julia/pull/20288
Let's just start over :p

[KristofferC]

Rip.

[pkofod]

Good thing you only yolo once... Is there an easy way to see what doc tests were affected, or is it just brute force going through them all on the latest master?

[KristofferC]

just run the tests and go through them I think

[pkofod]

Okay... Don't know if any of you have started, but I'm working my way though the spaces.

[pkofod]

Documenter: populating indices.
ERROR: LoadError: `makedocs` encountered an error. Terminating build

Is this expected during make -C doc doctest ?

[KristofferC]

Hmm.. I haven't seen it before.

[tkelman]

I'm not seeing that locally? nevermind I do, but only after it has run most or all of the doctests - I'm guessing that might be expected if the doctests are failing?

We should think about adding a doctest mode to documenter that outputs valid patch files you could just pipe to git apply. You'd want to manually review the change before committing it, but would be good to automate mechanical fixes like this.

[KristofferC]

That'd be pretty cool!

[pkofod]

I'm not seeing that locally?

I'll try to checkout master to see if it was any of my changes that caused it.

We should think about adding a doctest mode to documenter that outputs valid patch files you could just pipe to git apply. You'd want to manually review the change before committing it, but would be good to automate mechanical fixes like this.

good idea

[pkofod]

Hm, this is the full error

Documenter: populating indices.
ERROR: LoadError: `makedocs` encountered an error. Terminating build
Stacktrace:
 [1] runner(::Type{Documenter.Builder.RenderDocument}, ::Documenter.Documents.Document) at /home/pkm/julia/julia/doc/deps/v0.6/Documenter/src/Builder.jl:202
 [2] dispatch(::Type{Documenter.Builder.DocumentPipeline}, ::Documenter.Documents.Document) at /home/pkm/julia/julia/doc/deps/v0.6/Documenter/src/Selectors.jl:164
 [3] cd(::Documenter.##2#3{Documenter.Documents.Document}, ::String) at ./file.jl:69
 [4] #makedocs#1(::Bool, ::Array{Any,1}, ::Function) at /home/pkm/julia/julia/doc/deps/v0.6/Documenter/src/Documenter.jl:159
 [5] (::Documenter.#kw##makedocs)(::Array{Any,1}, ::Documenter.#makedocs) at ./<missing>:0
 [6] include_from_node1(::String) at ./loading.jl:539
 [7] include(::String) at ./sysimg.jl:14
 [8] process_options(::Base.JLOptions) at ./client.jl:304
 [9] _start() at ./client.jl:370
while loading /home/pkm/julia/julia/doc/make.jl, in expression starting on line 115
Makefile:54: recipe for target 'doctest' failed
make: *** [doctest] Error 1
make: Leaving directory '/home/pkm/julia/julia/doc'

is this simply because there were doctest errors?

[StefanKarpinski]

Wouldn't it be easier to just run all the doctests through julia and replace the output in the docs? Then doing git diff would show you the changes. Needing to do git apply to apply them seems like an unnecessary complication. Then the script that does that doesn't need to know anything about git or diffs.

[KristofferC]

That would remove the error checking part from the doctests I guess but perhaps it's fine to say that tests should just be in CI

[tkelman]

I wouldn't want running the doctests to write changes to base sources by default, what if you build from a release tarball and do that.

[StefanKarpinski]

Obviously not, but it could be a different make target.

[KristofferC]

@pkofod yes, if you run in strict mode then that will happen if there are any errors in the build

[KristofferC]

For now I suggest working locally with #20288 reverted, and when someone (maybe @pkofod) makes a PR that fixes all from that we all switch over. Else everything will conflict and it will be a mess.

[pkofod]

For now I suggest working locally with #20288 reverted, and when someone (maybe @pkofod) makes a PR that fixes all from that we all switch over. Else everything will conflict and it will be a mess.

I am on it, I've just been AFK for a while. I'll make a PR when they're adjusted. (edit is fixed in #20417 by vtjnash)

[ararslan]

I just want to say thank you all so much for doing this, it's fantastic! 💯

[KristofferC]

Nice job broses and sises.

[KristofferC]

Actually, #20297 is still open. Oh well. I close this anyway :P