From 37cd4cd2ca20b2297dc5b8045ad5afc94620aeab Mon Sep 17 00:00:00 2001 From: adigitoleo Date: Wed, 31 Jul 2024 01:16:16 +1000 Subject: [PATCH 1/4] docs: Add headers for easier Core, Base and stdlib reference This adds one new section (h2) and a nested subsection (h3) to the landing page of the Julia documentation website and associated PDF file. The new section provides a quick overview of the differences between `Core`, `Base` and the standard library, as well as a list of links to standard library packages. The list of standard library packages is thus duplicated in the website sidebar, but I don't think this is an issue because the sidebar is primarily intended for navigation, whereas this list is primarily intended to be used for referencing purposes. Partially addresses #28712, although I don't provide short descriptions of each standard library package. I think the appropriate place for that would be in module-level docstrings of the packages themselves, which are not currently available. --- doc/src/index.md | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/doc/src/index.md b/doc/src/index.md index 8c88af424e8e3..8abd15b9d5b82 100644 --- a/doc/src/index.md +++ b/doc/src/index.md @@ -76,7 +76,7 @@ and [Ruby](https://en.wikipedia.org/wiki/Ruby_(programming_language)). The most significant departures of Julia from typical dynamic languages are: - * The core language imposes very little; Julia Base and the standard library are written in Julia itself, including + * The core language imposes very little; [Julia Base and the standard library](@ref man-core-base-and-stdlib) are written in Julia itself, including primitive operations like integer arithmetic * A rich language of types for constructing and describing objects, that can also optionally be used to make type declarations @@ -126,3 +126,23 @@ 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 + +## [Julia Core, Base and the Standard Library](@id man-core-base-and-stdlib) + +```@docs; canonical=false +Core +Base +``` + +### [The Standard Library](@id man-stdlib) + +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) or [`import`](@ref) statement. +Links to available standard library packages are provided below, +and may also be found in the website sidebar. + +```@eval +import Markdown +list = sort(filter(x -> match(r"_jll$", x) === nothing, readdir(Sys.STDLIB))) +Markdown.parse(join("- [`" .* list .* "`](stdlib/" .* list .* ".html)", "\n")) +``` From 7cccae1ad421d7b84b33d3f85d606ff2a25bb896 Mon Sep 17 00:00:00 2001 From: adigitoleo Date: Thu, 1 Aug 2024 11:44:27 +1000 Subject: [PATCH 2/4] docs: Better integration of new stdlib docs with existing Base docs --- doc/src/base/base.md | 4 ++-- doc/src/index.md | 8 +++++++- 2 files changed, 9 insertions(+), 3 deletions(-) diff --git a/doc/src/base/base.md b/doc/src/base/base.md index 946f917682814..218dbca14021f 100644 --- a/doc/src/base/base.md +++ b/doc/src/base/base.md @@ -108,14 +108,14 @@ where :: ``` -## Standard Modules +## [Standard Modules](@id standard-modules) ```@docs Main Core Base ``` -## Base Submodules +## [Base Submodules](@id base-submodules) ```@docs Base.Broadcast Base.Docs diff --git a/doc/src/index.md b/doc/src/index.md index 8abd15b9d5b82..7ebf555ebe0c6 100644 --- a/doc/src/index.md +++ b/doc/src/index.md @@ -127,19 +127,25 @@ language. In addition to the above, some advantages of Julia over comparable sys * Powerful shell-like capabilities for managing other processes * Lisp-like macros and other metaprogramming facilities -## [Julia Core, Base and the Standard Library](@id man-core-base-and-stdlib) +## [Julia Standard Modules and the Standard Library](@id man-standard-modules-stdlib) + +The Julia runtime comes with [standard modules](@ref standard-modules), +which are essential namespaces that are usually loaded automatically. ```@docs; canonical=false Core Base ``` +Julia's `Base` module contains various [useful submodules](@id base-submodules). + ### [The Standard Library](@id man-stdlib) 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) or [`import`](@ref) statement. Links to available standard library packages are provided below, and may also be found in the website sidebar. +Their source code is available in the `Sys.STDLIB` directory of a Julia installation. ```@eval import Markdown From c81845663c9912ab17800343554add99c446e451 Mon Sep 17 00:00:00 2001 From: adigitoleo Date: Thu, 1 Aug 2024 11:47:06 +1000 Subject: [PATCH 3/4] fix: Fix typo @id -> @ref --- doc/src/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/src/index.md b/doc/src/index.md index 7ebf555ebe0c6..1c90cbc528034 100644 --- a/doc/src/index.md +++ b/doc/src/index.md @@ -137,7 +137,7 @@ Core Base ``` -Julia's `Base` module contains various [useful submodules](@id base-submodules). +Julia's `Base` module contains various [useful submodules](@ref base-submodules). ### [The Standard Library](@id man-stdlib) From cc4ba4224b9a6efabe515ecfc6d7df19f0d8824c Mon Sep 17 00:00:00 2001 From: adigitoleo Date: Tue, 6 Aug 2024 00:52:42 +1000 Subject: [PATCH 4/4] docs: Add list of stdlib _jll packages Addresses . --- doc/src/index.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/doc/src/index.md b/doc/src/index.md index 1c90cbc528034..d779f78b49d75 100644 --- a/doc/src/index.md +++ b/doc/src/index.md @@ -152,3 +152,14 @@ import Markdown list = sort(filter(x -> match(r"_jll$", x) === nothing, readdir(Sys.STDLIB))) Markdown.parse(join("- [`" .* list .* "`](stdlib/" .* list .* ".html)", "\n")) ``` + +Julia also provides various standard, pre-built binary libraries +of established software that is written in other languages. +By convention, these packages have names that end with `_jll`. +The [`using`](@ref) statement can load symbol names from these binary libraries: + +```@eval +import Markdown +list = sort(filter(x -> match(r"_jll$", x) !== nothing, readdir(Sys.STDLIB))) +Markdown.parse(join("- [`" .* list .* "`](stdlib/" .* list .* ".html)", "\n")) +```