split out a part of stdlib into a Base category in docs (#24461)

JuliaLang · Jan 9, 2018 · 8e7ae9f · 8e7ae9f
1 parent 9b5eed2
commit 8e7ae9f
Show file tree

Hide file tree

Showing 39 changed files with 84 additions and 110 deletions.
diff --git a/doc/.gitignore b/doc/.gitignore
@@ -1,4 +1,5 @@
 deps/
 _build/
 UnicodeData.txt
+src/stdlib/
 
diff --git a/doc/make.jl b/doc/make.jl
@@ -19,35 +19,23 @@ end
 symlink_q(tgt, link) = isfile(link) || symlink(tgt, link)
 cp_q(src, dest) = isfile(dest) || cp(src, dest)
 
-# make links for stdlib package docs
-if Sys.iswindows()
-    cp_q("../stdlib/DelimitedFiles/docs/src/index.md",        "src/stdlib/delimitedfiles.md")
-    cp_q("../stdlib/Test/docs/src/index.md",                  "src/stdlib/test.md")
-    cp_q("../stdlib/Mmap/docs/src/index.md",                  "src/stdlib/mmap.md")
-    cp_q("../stdlib/SharedArrays/docs/src/index.md",          "src/stdlib/sharedarrays.md")
-    cp_q("../stdlib/Profile/docs/src/index.md",               "src/stdlib/profile.md")
-    cp_q("../stdlib/Base64/docs/src/index.md",                "src/stdlib/base64.md")
-    cp_q("../stdlib/FileWatching/docs/src/index.md",          "src/stdlib/filewatching.md")
-    cp_q("../stdlib/CRC32c/docs/src/index.md",                "src/stdlib/crc32c.md")
-    cp_q("../stdlib/Dates/docs/src/index.md",                 "src/stdlib/dates.md")
-    cp_q("../stdlib/IterativeEigensolvers/docs/src/index.md", "src/stdlib/iterativeeigensolvers.md")
-    cp_q("../stdlib/Unicode/docs/src/index.md",               "src/stdlib/unicode.md")
-    cp_q("../stdlib/Distributed/docs/src/index.md",           "src/stdlib/distributed.md")
-    cp_q("../stdlib/Printf/docs/src/index.md",                "src/stdlib/printf.md")
-else
-    symlink_q("../../../stdlib/DelimitedFiles/docs/src/index.md",        "src/stdlib/delimitedfiles.md")
-    symlink_q("../../../stdlib/Test/docs/src/index.md",                  "src/stdlib/test.md")
-    symlink_q("../../../stdlib/Mmap/docs/src/index.md",                  "src/stdlib/mmap.md")
-    symlink_q("../../../stdlib/SharedArrays/docs/src/index.md",          "src/stdlib/sharedarrays.md")
-    symlink_q("../../../stdlib/Profile/docs/src/index.md",               "src/stdlib/profile.md")
-    symlink_q("../../../stdlib/Base64/docs/src/index.md",                "src/stdlib/base64.md")
-    symlink_q("../../../stdlib/FileWatching/docs/src/index.md",          "src/stdlib/filewatching.md")
-    symlink_q("../../../stdlib/CRC32c/docs/src/index.md",                "src/stdlib/crc32c.md")
-    symlink_q("../../../stdlib/Dates/docs/src/index.md",                 "src/stdlib/dates.md")
-    symlink_q("../../../stdlib/IterativeEigensolvers/docs/src/index.md", "src/stdlib/iterativeeigensolvers.md")
-    symlink_q("../../../stdlib/Unicode/docs/src/index.md",               "src/stdlib/unicode.md")
-    symlink_q("../../../stdlib/Distributed/docs/src/index.md",           "src/stdlib/distributed.md")
-    symlink_q("../../../stdlib/Printf/docs/src/index.md",                "src/stdlib/printf.md")
+# make links for stdlib package docs, this is needed until #522 in Documenter.jl is finished
+const STDLIB_DOCS = []
+const STDLIB_DIR = joinpath(@__DIR__, "..", "stdlib")
+for dir in readdir(STDLIB_DIR)
+    sourcefile = joinpath(STDLIB_DIR, dir, "docs", "src", "index.md")
+    if isfile(sourcefile)
+        cd(joinpath(@__DIR__, "src")) do
+            isdir("stdlib") || mkdir("stdlib")
+            targetfile = joinpath("stdlib", dir * ".md")
+            push!(STDLIB_DOCS, (stdlib = Symbol(dir), targetfile = targetfile))
+            if Sys.iswindows()
+                cp_q(sourcefile, targetfile)
+            else
+                symlink_q(sourcefile, targetfile)
+            end
+        end
+    end
 end
 
 const PAGES = [
@@ -93,42 +81,31 @@ const PAGES = [
         "manual/noteworthy-differences.md",
         "manual/unicode-input.md",
     ],
-    "Standard Library" => [
-        "stdlib/base.md",
-        "stdlib/collections.md",
-        "stdlib/math.md",
-        "stdlib/numbers.md",
-        "stdlib/strings.md",
-        "stdlib/arrays.md",
-        "stdlib/parallel.md",
-        "stdlib/distributed.md",
-        "stdlib/multi-threading.md",
-        "stdlib/linalg.md",
-        "stdlib/constants.md",
-        "stdlib/file.md",
-        "stdlib/delimitedfiles.md",
-        "stdlib/io-network.md",
-        "stdlib/punctuation.md",
-        "stdlib/sort.md",
-        "stdlib/pkg.md",
-        "stdlib/dates.md",
-        "stdlib/iterators.md",
-        "stdlib/test.md",
-        "stdlib/c.md",
-        "stdlib/libc.md",
-        "stdlib/libdl.md",
-        "stdlib/profile.md",
-        "stdlib/stacktraces.md",
-        "stdlib/simd-types.md",
-        "stdlib/base64.md",
-        "stdlib/mmap.md",
-        "stdlib/sharedarrays.md",
-        "stdlib/filewatching.md",
-        "stdlib/crc32c.md",
-        "stdlib/iterativeeigensolvers.md",
-        "stdlib/unicode.md",
-        "stdlib/printf.md",
+    "Base" => [
+        "base/base.md",
+        "base/collections.md",
+        "base/math.md",
+        "base/numbers.md",
+        "base/strings.md",
+        "base/arrays.md",
+        "base/parallel.md",
+        "base/multi-threading.md",
+        "base/linalg.md",
+        "base/constants.md",
+        "base/file.md",
+        "base/io-network.md",
+        "base/punctuation.md",
+        "base/sort.md",
+        "base/pkg.md",
+        "base/iterators.md",
+        "base/c.md",
+        "base/libc.md",
+        "base/libdl.md",
+        "base/stacktraces.md",
+        "base/simd-types.md",
     ],
+    "Standard Library" =>
+        [stdlib.targetfile for stdlib in STDLIB_DOCS],
     "Developer Documentation" => [
         "devdocs/reflection.md",
         "Documentation of Julia's Internals" => [
@@ -162,13 +139,13 @@ const PAGES = [
     ],
 ]
 
-using DelimitedFiles, Test, Mmap, SharedArrays, Profile, Base64, FileWatching, CRC32c,
-      Dates, IterativeEigensolvers, Unicode, Distributed, Printf
+for stdlib in STDLIB_DOCS
+    @eval using $(stdlib.stdlib)
+end
 
 makedocs(
     build     = joinpath(pwd(), "_build/html/en"),
-    modules   = [Base, Core, BuildSysImg, DelimitedFiles, Test, Mmap, SharedArrays, Profile,
-                 Base64, FileWatching, Dates, IterativeEigensolvers, Unicode, Distributed, Printf],
+    modules   = [Base, Core, BuildSysImg, [Module(stdlib.stdlib) for stdlib in STDLIB_DOCS]...],
     clean     = false,
     doctest   = "doctest" in ARGS,
     linkcheck = "linkcheck" in ARGS,

diff --git a/doc/src/stdlib/arrays.md → doc/src/base/arrays.md b/doc/src/stdlib/arrays.md → doc/src/base/arrays.md
diff --git a/doc/src/stdlib/base.md → doc/src/base/base.md b/doc/src/stdlib/base.md → doc/src/base/base.md
@@ -2,7 +2,7 @@
 
 ## Introduction
 
-The Julia standard library contains a range of functions and macros appropriate for performing
+Julia Base contains a range of functions and macros appropriate for performing
 scientific and numerical computing, but is also as broad as those of many general purpose programming
 languages.  Additional functionality is available from a growing collection of available packages.
 Functions are grouped by topic below.

diff --git a/doc/src/stdlib/c.md → doc/src/base/c.md b/doc/src/stdlib/c.md → doc/src/base/c.md
diff --git a/doc/src/stdlib/collections.md → doc/src/base/collections.md b/doc/src/stdlib/collections.md → doc/src/base/collections.md
diff --git a/doc/src/stdlib/constants.md → doc/src/base/constants.md b/doc/src/stdlib/constants.md → doc/src/base/constants.md
diff --git a/doc/src/stdlib/file.md → doc/src/base/file.md b/doc/src/stdlib/file.md → doc/src/base/file.md
diff --git a/doc/src/stdlib/index.md → doc/src/base/index.md b/doc/src/stdlib/index.md → doc/src/base/index.md
diff --git a/doc/src/stdlib/io-network.md → doc/src/base/io-network.md b/doc/src/stdlib/io-network.md → doc/src/base/io-network.md
diff --git a/doc/src/stdlib/iterators.md → doc/src/base/iterators.md b/doc/src/stdlib/iterators.md → doc/src/base/iterators.md
diff --git a/doc/src/stdlib/libc.md → doc/src/base/libc.md b/doc/src/stdlib/libc.md → doc/src/base/libc.md
diff --git a/doc/src/stdlib/libdl.md → doc/src/base/libdl.md b/doc/src/stdlib/libdl.md → doc/src/base/libdl.md
diff --git a/doc/src/stdlib/linalg.md → doc/src/base/linalg.md b/doc/src/stdlib/linalg.md → doc/src/base/linalg.md
diff --git a/doc/src/stdlib/math.md → doc/src/base/math.md b/doc/src/stdlib/math.md → doc/src/base/math.md
diff --git a/doc/src/stdlib/multi-threading.md → doc/src/base/multi-threading.md b/doc/src/stdlib/multi-threading.md → doc/src/base/multi-threading.md
diff --git a/doc/src/stdlib/numbers.md → doc/src/base/numbers.md b/doc/src/stdlib/numbers.md → doc/src/base/numbers.md
diff --git a/doc/src/stdlib/parallel.md → doc/src/base/parallel.md b/doc/src/stdlib/parallel.md → doc/src/base/parallel.md
diff --git a/doc/src/stdlib/pkg.md → doc/src/base/pkg.md b/doc/src/stdlib/pkg.md → doc/src/base/pkg.md
diff --git a/doc/src/stdlib/punctuation.md → doc/src/base/punctuation.md b/doc/src/stdlib/punctuation.md → doc/src/base/punctuation.md
diff --git a/doc/src/stdlib/simd-types.md → doc/src/base/simd-types.md b/doc/src/stdlib/simd-types.md → doc/src/base/simd-types.md
diff --git a/doc/src/stdlib/sort.md → doc/src/base/sort.md b/doc/src/stdlib/sort.md → doc/src/base/sort.md
diff --git a/doc/src/stdlib/stacktraces.md → doc/src/base/stacktraces.md b/doc/src/stdlib/stacktraces.md → doc/src/base/stacktraces.md
diff --git a/doc/src/stdlib/strings.md → doc/src/base/strings.md b/doc/src/stdlib/strings.md → doc/src/base/strings.md
diff --git a/doc/src/index.md b/doc/src/index.md
@@ -1,5 +1,10 @@
 # Julia Documentation
 
+* [Manual](#Manual-1)
+* [Base](#Base-1)
+* [Standard Library](#Standard-Library-1)
+* [Developer Documentation](#Developer-Documentation-1)
+
 ## Manual
 
   * [Introduction](@ref man-introduction)
@@ -42,7 +47,7 @@
   * [Noteworthy Differences from other Languages](@ref)
   * [Unicode Input](@ref)
 
-## Standard Library
+## Base
 
   * [Essentials](@ref)
   * [Collections and Data Structures](@ref)
@@ -57,26 +62,32 @@
   * [Linear Algebra](@ref)
   * [Constants](@ref lib-constants)
   * [Filesystem](@ref)
-  * [Delimited Files](@ref)
   * [I/O and Network](@ref)
   * [Punctuation](@ref)
   * [Sorting and Related Functions](@ref)
   * [Package Manager Functions](@ref)
-  * [Dates and Time](@ref stdlib-dates)
   * [Iteration utilities](@ref)
-  * [Unit Testing](@ref)
   * [C Interface](@ref)
   * [C Standard Library](@ref)
   * [Dynamic Linker](@ref)
   * [StackTraces](@ref)
   * [SIMD Support](@ref)
-  * [Profiling](@ref lib-profiling)
-  * [Memory-mapped I/O](@ref)
+
+## Standard Library
+
   * [Base64](@ref)
+  * [CRC32c](@ref)
+  * [Dates and Time](@ref stdlib-dates)
+  * [Delimited Files](@ref)
+  * [Distributed Computing](@ref)
   * [File Events](@ref lib-filewatching)
   * [Iterative Eigensolvers](@ref lib-itereigen)
-  * [Unicode](@ref)
+  * [Memory-mapped I/O](@ref)
   * [Printf](@ref)
+  * [Profiling](@ref lib-profiling)
+  * [Shared Arrays](@ref)
+  * [Unit Testing](@ref)
+  * [Unicode](@ref)
 
 ## Developer Documentation
 

diff --git a/doc/src/manual/arrays.md b/doc/src/manual/arrays.md
@@ -944,7 +944,7 @@ as a given sparse matrix `S`, or that the resulting sparse matrix has density `d
 element has a probability `d` of being non-zero.
 
 Details can be found in the [Sparse Vectors and Matrices](@ref stdlib-sparse-arrays)
-section of the standard library reference.
+section of the Julia Base reference.
 
 | Sparse                     | Dense                  | Description                                                                                                                                                           |
 |:-------------------------- |:---------------------- |:--------------------------------------------------------------------------------------------------------------------------------------------------------------------- |

diff --git a/doc/src/manual/control-flow.md b/doc/src/manual/control-flow.md
@@ -937,7 +937,7 @@ In addition to [`yieldto`](@ref), a few other basic functions are needed to use
 ### Tasks and events
 
 Most task switches occur as a result of waiting for events such as I/O requests, and are performed
-by a scheduler included in the standard library. The scheduler maintains a queue of runnable tasks,
+by a scheduler included in Julia Base. The scheduler maintains a queue of runnable tasks,
 and executes an event loop that restarts tasks based on external events such as message arrival.
 
 The basic function for waiting for an event is [`wait`](@ref). Several objects implement [`wait`](@ref);

diff --git a/doc/src/manual/conversion-and-promotion.md b/doc/src/manual/conversion-and-promotion.md
@@ -150,7 +150,7 @@ is never used in the function body. In this example, since the type is a singlet
 would never be any reason to use its value within the body.
 
 All instances of some abstract types are by default considered "sufficiently similar"
-that a universal `convert` definition is provided in the standard library.
+that a universal `convert` definition is provided in Julia Base.
 For example, this definition states that it's valid to `convert` any `Number` type to
 any other by calling a 1-argument constructor:
 
@@ -231,7 +231,7 @@ try again. That's all there is to it: nowhere else does one ever need to worry a
 to a common numeric type for arithmetic operations -- it just happens automatically. There are
 definitions of catch-all promotion methods for a number of other arithmetic and mathematical functions
 in [`promotion.jl`](https://github.com/JuliaLang/julia/blob/master/base/promotion.jl), but beyond
-that, there are hardly any calls to `promote` required in the Julia standard library. The most
+that, there are hardly any calls to `promote` required in Julia Base. The most
 common usages of `promote` occur in outer constructors methods, provided for convenience, to allow
 constructor calls with mixed types to delegate to an inner type with fields promoted to an appropriate
 common type. For example, recall that [`rational.jl`](https://github.com/JuliaLang/julia/blob/master/base/rational.jl)
@@ -270,7 +270,7 @@ promote_rule(::Type{Float64}, ::Type{Float32}) = Float64
 
 one declares that when 64-bit and 32-bit floating-point values are promoted together, they should
 be promoted to 64-bit floating-point. The promotion type does not need to be one of the argument
-types, however; the following promotion rules both occur in Julia's standard library:
+types, however; the following promotion rules both occur in Julia Base:
 
 ```julia
 promote_rule(::Type{UInt8}, ::Type{Int8}) = Int

diff --git a/doc/src/manual/interfaces.md b/doc/src/manual/interfaces.md
@@ -131,7 +131,7 @@ julia> sum(Squares(1803))
 1955361914
 ```
 
-This is a very common pattern throughout the Julia standard library: a small set of required methods
+This is a very common pattern throughout Julia Base: a small set of required methods
 define an informal interface that enable many fancier behaviors. In some cases, types will want
 to additionally specialize those extra behaviors when they know a more efficient algorithm can
 be used in their specific case.
@@ -234,7 +234,7 @@ ourselves, we can officially define it as a subtype of an [`AbstractArray`](@ref
 
 If a type is defined as a subtype of `AbstractArray`, it inherits a very large set of rich behaviors
 including iteration and multidimensional indexing built on top of single-element access.  See
-the [arrays manual page](@ref man-multi-dim-arrays) and [standard library section](@ref lib-arrays) for more supported methods.
+the [arrays manual page](@ref man-multi-dim-arrays) and the [Julia Base section](@ref lib-arrays) for more supported methods.
 
 A key part in defining an `AbstractArray` subtype is [`IndexStyle`](@ref). Since indexing is
 such an important part of an array and often occurs in hot loops, it's important to make both
@@ -373,7 +373,7 @@ julia> copy(A)
 ```
 
 In addition to all the iterable and indexable methods from above, these types can also interact
-with each other and use most of the methods defined in the standard library for `AbstractArrays`:
+with each other and use most of the methods defined in Julia Base for `AbstractArrays`:
 
 ```jldoctest squarevectype
 julia> A[SquaresVector(3)]

diff --git a/doc/src/manual/introduction.md b/doc/src/manual/introduction.md
@@ -27,7 +27,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; the standard library is written in Julia itself, including
+  * The core language imposes very little; Julia Base and the standard library is 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

diff --git a/doc/src/manual/linear-algebra.md b/doc/src/manual/linear-algebra.md
@@ -261,7 +261,7 @@ in linear algebra.
 
 The following table summarizes the types of matrix factorizations that have been implemented in
 Julia. Details of their associated methods can be found in the [Linear Algebra](@ref) section
-of the standard library documentation.
+of the Julia Base documentation.
 
 | Type              | Description                                                                                                    |
 |:----------------- |:-------------------------------------------------------------------------------------------------------------- |

diff --git a/doc/src/manual/metaprogramming.md b/doc/src/manual/metaprogramming.md
@@ -676,7 +676,7 @@ Notice that it would not be possible to write this as a function, since only the
 condition is available and it would be impossible to display the expression that computed it in
 the error message.
 
-The actual definition of `@assert` in the standard library is more complicated. It allows the
+The actual definition of `@assert` in Julia Base is more complicated. It allows the
 user to optionally specify their own error message, instead of just printing the failed expression.
 Just like in functions with a variable number of arguments, this is specified with an ellipses
 following the last argument:
@@ -776,7 +776,7 @@ end
 ```
 
 Here, we want `t0`, `t1`, and `val` to be private temporary variables, and we want `time` to refer
-to the [`time`](@ref) function in the standard library, not to any `time` variable the user
+to the [`time`](@ref) function in Julia Base, not to any `time` variable the user
 might have (the same applies to `println`). Imagine the problems that could occur if the user
 expression `ex` also contained assignments to a variable called `t0`, or defined its own `time`
 variable. We might get errors, or mysteriously incorrect behavior.
@@ -787,7 +787,7 @@ to (and not declared global), declared local, or used as a function argument nam
 it is considered global. Local variables are then renamed to be unique (using the [`gensym`](@ref)
 function, which generates new symbols), and global variables are resolved within the macro definition
 environment. Therefore both of the above concerns are handled; the macro's locals will not conflict
-with any user variables, and `time` and `println` will refer to the standard library definitions.
+with any user variables, and `time` and `println` will refer to the Julia Base definitions.
 
 One problem remains however. Consider the following use of this macro:
 

diff --git a/doc/src/manual/methods.md b/doc/src/manual/methods.md
@@ -593,7 +593,7 @@ The subtypes of `AbstractArray` typically implement two methods to
 achieve this:
 A method to convert the input array to a subtype of a specific `AbstractArray{T, N}` abstract type;
 and a method to make a new uninitialized array with a specific element type.
-Sample implementations of these can be found in the standard library.
+Sample implementations of these can be found in Julia Base.
 Here is a basic example usage of them, guaranteeing that `input` and
 `output` are of the same type:
 

diff --git a/doc/src/manual/modules.md b/doc/src/manual/modules.md
@@ -126,7 +126,7 @@ Core contains all identifiers considered "built in" to the language, i.e. part o
 and not libraries. Every module implicitly specifies `using Core`, since you can't do anything
 without those definitions.
 
-Base is the standard library (the contents of base/). All modules implicitly contain `using Base`,
+Base is a module that contains basic functionality (the contents of base/). All modules implicitly contain `using Base`,
 since this is needed in the vast majority of cases.
 
 ### Default top-level definitions and bare modules

diff --git a/doc/src/manual/networking-and-streams.md b/doc/src/manual/networking-and-streams.md
@@ -100,7 +100,7 @@ Note that `a` is written to [`STDOUT`](@ref) by the [`write`](@ref) function and
 value is `1` (since `0x61` is one byte).
 
 For text I/O, use the [`print`](@ref) or [`show`](@ref) methods, depending on your needs (see
-the standard library reference for a detailed discussion of the difference between the two):
+the Julia Base reference for a detailed discussion of the difference between the two):
 
 ```jldoctest
 julia> print(STDOUT, 0x61)

diff --git a/doc/src/manual/performance-tips.md b/doc/src/manual/performance-tips.md
@@ -666,7 +666,7 @@ of `fill_twos!` for different types of `a`.
 
 The second form is also often better style and can lead to more code reuse.
 
-This pattern is used in several places in the standard library. For example, see `hvcat_fill`
+This pattern is used in several places in Julia Base. For example, see `hvcat_fill`
 in [`abstractarray.jl`](https://github.com/JuliaLang/julia/blob/master/base/abstractarray.jl), or
 the [`fill!`](@ref) function, which we could have used instead of writing our own `fill_twos!`.
 
@@ -804,7 +804,7 @@ statement can be found [on the mailing list](https://groups.google.com/forum/#!m
 Perhaps even worse than the run-time impact is the compile-time impact: Julia will compile specialized
 functions for each different `Car{Make, Model}`; if you have hundreds or thousands of such types,
 then every function that accepts such an object as a parameter (from a custom `get_year` function
-you might write yourself, to the generic `push!` function in the standard library) will have hundreds
+you might write yourself, to the generic `push!` function in Julia Base) will have hundreds
 or thousands of variants compiled for it.  Each of these increases the size of the cache of compiled
 code, the length of internal lists of methods, etc.  Excess enthusiasm for values-as-parameters
 can easily waste enormous resources.

diff --git a/doc/src/manual/style-guide.md b/doc/src/manual/style-guide.md
@@ -110,7 +110,7 @@ function double!(a::AbstractArray{<:Number})
 end
 ```
 
-The Julia standard library uses this convention throughout and contains examples of functions
+Julia Base uses this convention throughout and contains examples of functions
 with both copying and modifying forms (e.g., [`sort`](@ref) and [`sort!`](@ref)), and others
 which are just modifying (e.g., [`push!`](@ref), [`pop!`](@ref), [`splice!`](@ref)).  It
 is typical for such functions to also return the modified array for convenience.

diff --git a/doc/src/stdlib/.gitignore b/doc/src/stdlib/.gitignore
diff --git a/stdlib/Logging/docs/src/index.md b/stdlib/Logging/docs/src/index.md