Better documentation of stdlibs

[carstenbauer]

A lot of functionality has been moved from Base to stdlibs. However, for people who haven't been part of this process (especially beginners) it is not really transparent which stdlibs exist and what their purpose is.

The documentation doesn't seem to contain a list of all stdlibs with short descriptions. I think such a list would be very useful as a compact overview of all stdlibs.

The only kind of overview is the navigation pane. There, however, names do not match actual stdlib names and short descriptions are missing.

1. Do people agree that such a list would be good to have?
2. Where should such a table go?

[fredrikekre]

I think it could be good to have somewhere in the beginning, where we describe what Base includes, and then describe the stdlibs with links to their sections.

[monsij]

@fredrikekre @crstnbr Is this somewhat related to #30469 ?

[ViralBShah]

I think the documentation now does a pretty good job of Base vs. stdlib documentation. The doc coverage is also much higher than when this issue was filed. Can we close?

[carstenbauer]

@ViralBShah While I agree that the documentation has been improved, I still can't find a table (or something similar) in the Manual section that points to the available stdlibs. (The stdlib sections in the navigation pain also still don't match the actual stdlib names. But I think that a proper listing in the Manual section is much better/more important.)

[ViralBShah]

Yes, true. If you have a moment, would you be able to provide a PR with such a table?

[adigitoleo]

I guess the _jll modules should be excluded from the list? Or put in their own section?

Unless I'm missing something, getting the list is quite simple: readdir(Sys.STDLIB).

Or, without the _jll wrappers:

filter(x -> match(r"_jll$", x) === nothing, readdir(Sys.STDLIB))

Just a matter of pretty printing them into a list with links, might have a go tomorrow.

[adigitoleo]

I tried to compile the docs with the following changes, but Documenter doesn't like it. Don't really have time to fiddle with this at the moment, I'll leave it here in case it is useful:

diff --git a/doc/src/index.md b/doc/src/index.md
index e9319b18a9..32fc514b42 100644
--- a/doc/src/index.md
+++ b/doc/src/index.md
@@ -107,3 +107,16 @@ language. In addition to the above, some advantages of Julia over comparable sys
   * Call C functions directly (no wrappers or special APIs needed)
   * Powerful shell-like capabilities for managing other processes
   * Lisp-like macros and other metaprogramming facilities
+
+### [Core, Base and the Standard Library](@id man-core-base-stdlib)
+
+```@docs
+Core
+Base
+```
+
+The Julia standard library contains additional, commonly used packages that are installed alongside the Julia runtime by default. To use a standard library package, it is first necessary to load the package with a [`using`](@ref) statement. The table below lists all standard library packages:
+
+```@eval
+"- [`" .* filter(x -> match(r"_jll$", x) === nothing, readdir(Sys.STDLIB)) .* "`](@ref)"
+```

The first part was an attempt to splice in the output of ?Core and ?Docs to give a brief overview of the difference. After that is obviously the list of stdlib packages. It could be nice to give them each a one line summary, although the names are fairly descriptive.

[pbouffard]

Came here when trying to find a single canonical URL to link a Julia newbie to when first mentioning "the standard library". I couldn't find a way to link to a whole section of the docs - I wonder if there could be a page at the start of the Standard Library section called something like "Introduction" that could be linked to. That could have a brief description as in the earlier comment, ie.

The Julia standard library contains additional, commonly used packages that are installed alongside the Julia runtime by default. To use a standard library package, it is first necessary to load the package with a [`using`](@ref) statement. 

The automatic table of the packages themselves would be great to have right there but as I say I'm looking more for a link that answers "what is the Julia Standard Library" more than "what is in the Julia Standard Library.

The first mention of "standard library" in https://docs.julialang.org/en/v1/#man-introduction can link there too.

[adigitoleo]

I have managed to get something working with documenter.jl, the stdlib modules are just in a simple markdown list rather than a table. I'll open a PR shortly, let me know if the section headers look OK or if there is any other feedback. I thought I'd just put this section at the end of the landing page (index.html) but am open to moving it somewhere else.

@pbouffard You will get links for the two new headings as seen in the following screenshot:

[pbouffard]

@pbouffard You will get links for the two new headings as seen in the following screenshot:

Fantastic, thanks!

Would this get backported at all? It would be nice (for me and colleagues anyway) to have this for Julia 1.9.

[carstenbauer]

If this qualifies for a backport - I have no idea if it does - I would expect that it would only go into 1.10 since it is the new LTS.