Convert julia-repl blocks to jldoctest format (#58594)

Convert appropriate julia-repl code blocks to jldoctest format to enable
automatic testing. In addition, this introduces a new `nodoctest =
"reason"`
pattern to annotate code blocks that are deliberate not doctested, so
future
readers will know not to try.

Many code blocks are converted, in particular:

- Manual pages: arrays.md, asynchronous-programming.md, functions.md,
  integers-and-floating-point-numbers.md, metaprogramming.md,
  multi-threading.md, performance-tips.md, variables.md,
  variables-and-scoping.md
- Base documentation: abstractarray.jl, bitarray.jl, expr.jl, file.jl,
  float.jl, iddict.jl, path.jl, scopedvalues.md, sort.md
- Standard library: Dates/conversions.jl, Random/RNGs.jl,
  Sockets/addrinfo.jl

Key changes:
- Add filters for non-deterministic output (timing, paths, memory
addresses)
- Add setup/teardown for filesystem operations
- Fix parentmodule(M) usage in expr.jl for doctest compatibility
- Document double escaping requirement for regex filters in docstrings
- Update AGENTS.md with test running instructions

Note: Some julia-repl blocks were intentionally left unchanged when they
demonstrate language internals subject to change or contain
non-deterministic output that cannot be properly filtered.

Refs #56921

---------

Co-authored-by: Keno Fischer <[email protected]>
Co-authored-by: Claude <[email protected]>

Author: Keno

AGENTS.md

@@ -38,10 +38,23 @@ The test system supports doing this automatically (see below).
 
 ### Doctests
 
-If you have changed doctests (i.e. any `jldoctest` code block), you should run the doctests before
-preparing a PR. See `doc/README.md` for how to do this. For instructions on writing doctests, see
-`doc/src/devdocs/contributing/jldoctests.md`. Note that the doctests may take up to 15 minutes.
-Do not terminate the doctests before completion. If you are ChatGPT, you may have to increase yield_timeout_ms.
+#### Writing doctests
+
+If you are asked to write new doctests, first review `doc/src/devdocs/contributing/jldoctests.md`
+for best practices.
+
+#### Verifying doctests
+If you have changed any `jldoctest` code blocks you should take
+the following steps to verify your work:
+- Review `doc/src/devdocs/contributing/jldoctests.md`. In particular, determine
+  if any of the changed doctests require filters, labels or setup code.
+- Run the doctests to verify that your change works:
+    - To run doctest with the pre-built juliaup: `make -C doc doctest=true  revise=true JULIA_EXECUTABLE=$HOME/.juliaup/bin/julia`
+    - To run doctest with in-trr julia (preferred): `make -C doc doctest=true revise=true`. Do not pass any other options.
+    - IMPORTANT: The doctests may take up to 15 minutes. Do NOT terminate the doctests before completion. Do NOT use a timeout for doctests.
+    - If you are ChatGPT, you may have to increase yield_timeout_ms.
+
+Follow these steps for EVERY change you make in a doctest.
 
 ### Test changes
 

base/abstractarray.jl

@@ -796,7 +796,7 @@ julia> similar(1:10, 1, 4)
 Conversely, `similar(trues(10,10), 2)` returns an uninitialized `BitVector` with two
 elements since `BitArray`s are both mutable and can support 1-dimensional arrays:
 
-```julia-repl
+```jldoctest; filter = r"[01]"
 julia> similar(trues(10,10), 2)
 2-element BitVector:
  0

base/bitarray.jl

@@ -53,7 +53,7 @@ Construct an undef [`BitArray`](@ref) with the given dimensions.
 Behaves identically to the [`Array`](@ref) constructor. See [`undef`](@ref).
 
 # Examples
-```julia-repl
+```jldoctest; filter = r"[01]"
 julia> BitArray(undef, 2, 2)
 2×2 BitMatrix:
  0  0

base/expr.jl

@@ -144,15 +144,15 @@ There are differences between `@macroexpand` and [`macroexpand`](@ref).
   expands with respect to the module in which it is called.
 
 This is best seen in the following example:
-```julia-repl
+```jldoctest
 julia> module M
            macro m()
                1
            end
            function f()
                (@macroexpand(@m),
                 macroexpand(M, :(@m)),
-                macroexpand(Main, :(@m))
+                macroexpand(parentmodule(M), :(@m))
                )
            end
        end

base/file.jl

@@ -164,7 +164,7 @@ required intermediate directories.
 Return `path`.
 
 # Examples
-```julia-repl
+```jldoctest; setup = :(curdir = pwd(); testdir = mktempdir(); cd(testdir)), teardown = :(cd(curdir); rm(testdir, recursive=true)), filter = r"^\\".*testingdir\\"\$"
 julia> mkdir("testingdir")
 "testingdir"
 
@@ -516,7 +516,7 @@ If the file does not exist a new file is created.
 Return `path`.
 
 # Examples
-```julia-repl
+```jldoctest; setup = :(curdir = pwd(); testdir = mktempdir(); cd(testdir)), teardown = :(cd(curdir); rm(testdir, recursive=true)), filter = r"[\\d\\.]+e[\\+\\-]?\\d+"
 julia> write("my_little_file", 2);
 
 julia> mtime("my_little_file")
@@ -1134,7 +1134,7 @@ for (path, dirs, files) in walkdir(".")
 end
 ```
 
-```julia-repl
+```jldoctest; setup = :(prevdir = pwd(); tmpdir = mktempdir(); cd(tmpdir)), teardown = :(cd(prevdir); rm(tmpdir, recursive=true))
 julia> mkpath("my/test/dir");
 
 julia> itr = walkdir("my");

base/float.jl

@@ -83,7 +83,7 @@ julia> NaN == NaN, isequal(NaN, NaN), isnan(NaN)
 !!! note
     Always use [`isnan`](@ref) or [`isequal`](@ref) for checking for `NaN`.
     Using `x === NaN` may give unexpected results:
-    ```julia-repl
+    ```jldoctest
     julia> reinterpret(UInt32, NaN32)
     0x7fc00000
 

base/iddict.jl

@@ -12,7 +12,7 @@ the same, so they get overwritten. The `IdDict` hashes by object-id, and thus
 preserves the 3 different keys.
 
 # Examples
-```julia-repl
+```jldoctest; filter = r"  \\S+ +=> \\S+" => "  KEY => VALUE"
 julia> Dict(true => "yes", 1 => "no", 1.0 => "maybe")
 Dict{Real, String} with 1 entry:
   1.0 => "maybe"

base/path.jl

@@ -633,7 +633,7 @@ the [Freedesktop File URI spec](https://www.freedesktop.org/wiki/Specifications/
 julia> uripath("/home/user/example file.jl") # On a unix machine
 "file://<hostname>/home/user/example%20file.jl"
 
-juila> uripath("C:\\Users\\user\\example file.jl") # On a windows machine
+julia> uripath("C:\\Users\\user\\example file.jl") # On a windows machine
 "file:///C:/Users/user/example%20file.jl"
 ```
 """

doc/make.jl

@@ -318,7 +318,6 @@ if use_revise
 end
 function maybe_revise(ex)
     use_revise || return ex
-    STDLIB_DIR = Sys.STDLIB
     STDLIBS = filter!(x -> isfile(joinpath(STDLIB_DIR, x, "src", "$(x).jl")), readdir(STDLIB_DIR))
     return quote
         $ex

doc/src/base/scopedvalues.md

@@ -27,38 +27,57 @@ Let's first look at an example of **lexical** scope. A `let` statement begins
 a new lexical scope within which the outer definition of `x` is shadowed by
 it's inner definition.
 
-```julia
+```jldoctest
+julia> x = 1
+1
+
+julia> let x = 5
+           @show x
+       end;
+x = 5
+
+julia> @show x;
 x = 1
-let x = 5
-    @show x # 5
-end
-@show x # 1
 ```
 
 In the following example, since Julia uses lexical scope, the variable `x` in the body
 of `f` refers to the `x` defined in the global scope, and entering a `let` scope does
 not change the value `f` observes.
 
-```julia
+```jldoctest
+julia> x = 1
+1
+
+julia> f() = @show x
+f (generic function with 1 method)
+
+julia> let x = 5
+           f()
+       end;
+x = 1
+
+julia> f();
 x = 1
-f() = @show x
-let x = 5
-    f() # 1
-end
-f() # 1
 ```
 
 Now using a `ScopedValue` we can use **dynamic** scoping.
 
-```julia
-using Base.ScopedValues
+```jldoctest
+julia> using Base.ScopedValues
 
-x = ScopedValue(1)
-f() = @show x[]
-with(x=>5) do
-    f() # 5
-end
-f() # 1
+julia> x = ScopedValue(1)
+ScopedValue{Int64}(1)
+
+julia> f() = @show x[]
+f (generic function with 1 method)
+
+julia> with(x=>5) do
+           f()
+       end;
+x[] = 5
+
+julia> f();
+x[] = 1
 ```
 
 Note that the observed value of the `ScopedValue` is dependent on the execution