From b47c46cefb3ac635761a2688aecd0d3650d68ce6 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Fri, 23 May 2025 00:09:01 +0000
Subject: [PATCH] Docs: Update doctest info, enhance stdlib script

- Revise `doc/README.md` warning for `JULIA_EXECUTABLE` usage
  with doctests, updating to current GFM admonition syntax
  for improved clarity.
- Enhance `contrib/print_sorted_stdlibs.jl` script:
    - Add `--only-sysimg` option to accurately list standard
      libraries built into the system image.
    - Refine internal logic for sysimage-based filtering and
      ensure original comment state is preserved.

These modifications aim to provide clearer documentation and more
effective tooling for you and AI agents managing Julia doctest
environments and standard library configurations.
---
 contrib/print_sorted_stdlibs.jl | 22 ++++++++++++++++++----
 doc/README.md                   |  8 ++++++++
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/contrib/print_sorted_stdlibs.jl b/contrib/print_sorted_stdlibs.jl
index 6bc2023c4f1cc..c4cf391efb623 100644
--- a/contrib/print_sorted_stdlibs.jl
+++ b/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
diff --git a/doc/README.md b/doc/README.md
index be5426018084d..d282485bc584a 100644
--- a/doc/README.md
+++ b/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`).