Docs: Update doctest info, enhance stdlib script (#58503)

- Revise `doc/README.md` to mention `JULIA_EXECUTABLE` usage with
doctests, adding a warning regarding built-in stdlibs
- Enhance `contrib/print_sorted_stdlibs.jl` script to add
`--only-sysimg` option to accurately list standard libraries built into
the system image.

These modifications aim to provide clearer documentation and more
effective tooling for contributors and AI agents wanting to run the
doctests without building julia from scratch.

Co-authored-by: google-labs-jules[bot] <161369871+google-labs-jules[bot]@users.noreply.github.com>

Author: Keno

contrib/print_sorted_stdlibs.jl

@@ -12,12 +12,13 @@ function check_flag(flag)
 end
 
 if check_flag("--help") || check_flag("-h")
-    println("Usage: julia print_sorted_stdlibs.jl [stdlib_dir] [--exclude-jlls] [--exclude-sysimage]")
+    println("Usage: julia print_sorted_stdlibs.jl [stdlib_dir] [--exclude-jlls] [--exclude-sysimage] [--only-sysimg]")
 end
 
 # Allow users to ask for JLL or no JLLs
 exclude_jlls = check_flag("--exclude-jlls")
 exclude_sysimage = check_flag("--exclude-sysimage")
+only_sysimage = check_flag("--only-sysimg")
 
 # Default to the `stdlib/vX.Y` directory
 STDLIB_DIR = get(ARGS, 1, joinpath(@__DIR__, "..", "usr", "share", "julia", "stdlib"))
@@ -81,9 +82,19 @@ if exclude_jlls
     filter!(p -> !endswith(p, "_jll"), sorted_projects)
 end
 
-if exclude_sysimage
-    loaded_modules = Set(map(k->k.name, collect(keys(Base.loaded_modules))))
-    filter!(p->!in(p, loaded_modules), sorted_projects)
+if only_sysimage && exclude_sysimage
+    println(stderr, "Warning: --only-sysimg and --exclude-sysimage are mutually exclusive. Prioritizing --only-sysimg.")
+    exclude_sysimage = false
+end
+
+if only_sysimage || exclude_sysimage
+    loaded_modules_set = Set(map(k->k.name, collect(keys(Base.loaded_modules))))
+
+    if only_sysimage
+        filter!(p -> in(p, loaded_modules_set), sorted_projects)
+    else
+        filter!(p -> !in(p, loaded_modules_set), sorted_projects)
+    end
 end
 
 # Print out sorted projects, ready to be pasted into `sysimg.jl`
@@ -92,6 +103,9 @@ println("    # Stdlibs sorted in dependency, then alphabetical, order by contrib
 if exclude_jlls
     println("    # Run with the `--exclude-jlls` option to filter out all JLL packages")
 end
+if only_sysimage
+    println("    # Run with the `--only-sysimg` option to filter for only packages included in the system image")
+end
 if exclude_sysimage
     println("    # Run with the `--exclude-sysimage` option to filter out all packages included in the system image")
 end

doc/README.md

@@ -27,3 +27,11 @@ $ make -C doc doctest=true
 ```
 
 from the root directory.
+
+## Customizing Doctest Execution
+
+By default, doctests are run using the in-tree Julia executable.
+This behavior can be changed by setting the `JULIA_EXECUTABLE` Makefile variable.
+
+> [!WARNING]
+> Using a custom `JULIA_EXECUTABLE` will not pick up changes to docstrings for Base or any standard library built into the system image. To see the list of standard libraries that are part of the system image, you can run the `contrib/print_sorted_stdlibs.jl` script (e.g., `julia contrib/print_sorted_stdlibs.jl --only-sysimg`).