Add docstest=only option to docs/make.jl (#32376)

* Bump Documenter to 0.23.1 * Documenter now requires docstring doctests to have their own metadata in the corresponding module. Remove all the now redundant at-meta blocks from the standard library .md files and add the necessary module-level metadata in make.jl
JuliaLang · Aug 1, 2019 · 4324531 · 4324531
1 parent eee51db
commit 4324531
Show file tree

Hide file tree

Showing 15 changed files with 23 additions and 107 deletions.
diff --git a/doc/Manifest.toml b/doc/Manifest.toml
@@ -13,15 +13,15 @@ uuid = "8ba89e20-285c-5b6f-9357-94700520ee1b"
 
 [[DocStringExtensions]]
 deps = ["LibGit2", "Markdown", "Pkg", "Test"]
-git-tree-sha1 = "4d30e889c9f106a51ffa4791a88ffd4765bf20c3"
+git-tree-sha1 = "0513f1a8991e9d83255e0140aace0d0fc4486600"
 uuid = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
-version = "0.7.0"
+version = "0.8.0"
 
 [[Documenter]]
-deps = ["Base64", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Unicode"]
-git-tree-sha1 = "38509269fc99a9bc450fdb9e17e805021f3e5b1b"
+deps = ["Base64", "DocStringExtensions", "InteractiveUtils", "JSON", "LibGit2", "Logging", "Markdown", "REPL", "Test", "Unicode"]
+git-tree-sha1 = "1dba3854d6b0e35b3ed77f84419efbaf81f28886"
 uuid = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
-version = "0.22.4"
+version = "0.23.1"
 
 [[DocumenterLaTeX]]
 deps = ["Documenter", "Test"]
@@ -34,10 +34,10 @@ deps = ["Markdown"]
 uuid = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 
 [[JSON]]
-deps = ["Dates", "Distributed", "Mmap", "Sockets", "Test", "Unicode"]
-git-tree-sha1 = "1f7a25b53ec67f5e9422f1f551ee216503f4a0fa"
+deps = ["Dates", "Mmap", "Parsers", "Unicode"]
+git-tree-sha1 = "b34d7cef7b337321e97d22242c3c2b91f476748e"
 uuid = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
-version = "0.20.0"
+version = "0.21.0"
 
 [[LibGit2]]
 uuid = "76f85450-5226-5b5a-8eaa-529ad045b433"
@@ -52,6 +52,12 @@ uuid = "d6f4376e-aef5-505a-96c1-9c027394607a"
 [[Mmap]]
 uuid = "a63ad114-7e13-5084-954f-fe012c677804"
 
+[[Parsers]]
+deps = ["Dates", "Test"]
+git-tree-sha1 = "db2b35dedab3c0e46dc15996d170af07a5ab91c9"
+uuid = "69de0a69-1ddd-5017-9359-2bf0b02dc9f0"
+version = "0.3.6"
+
 [[Pkg]]
 deps = ["Dates", "LibGit2", "Markdown", "Printf", "REPL", "Random", "SHA", "UUIDs"]
 uuid = "44cfe95a-1eb2-52ea-b672-e2afdf69b78f"

diff --git a/doc/make.jl b/doc/make.jl
@@ -147,7 +147,13 @@ const PAGES = [
 
 for stdlib in STDLIB_DOCS
     @eval using $(stdlib.stdlib)
+    # All standard library modules get `using $STDLIB` as their global
+    DocMeta.setdocmeta!(Base.root_module(Base, stdlib.stdlib), :DocTestSetup, :(using $(stdlib.stdlib)), recursive=true)
 end
+# A few standard libraries need more than just the module itself in the DocTestSetup.
+# This overwrites the existing ones from above though, hence the warn=false.
+DocMeta.setdocmeta!(SparseArrays, :DocTestSetup, :(using SparseArrays, LinearAlgebra), recursive=true, warn=false)
+DocMeta.setdocmeta!(UUIDs, :DocTestSetup, :(using UUIDs, Random), recursive=true, warn=false)
 
 const render_pdf = "pdf" in ARGS
 let r = r"buildroot=(.+)", i = findfirst(x -> occursin(r, x), ARGS)
@@ -171,7 +177,7 @@ makedocs(
     build     = joinpath(buildroot, "doc", "_build", (render_pdf ? "pdf" : "html"), "en"),
     modules   = [Base, Core, [Base.root_module(Base, stdlib.stdlib) for stdlib in STDLIB_DOCS]...],
     clean     = true,
-    doctest   = ("doctest=fix" in ARGS) ? (:fix) : ("doctest=true" in ARGS) ? true : false,
+    doctest   = ("doctest=fix" in ARGS) ? (:fix) : ("doctest=only" in ARGS) ? (:only) : ("doctest=true" in ARGS) ? true : false,
     linkcheck = "linkcheck=true" in ARGS,
     linkcheck_ignore = ["https://bugs.kde.org/show_bug.cgi?id=136779"], # fails to load from nanosoldier?
     strict    = true,

diff --git a/stdlib/Base64/docs/src/index.md b/stdlib/Base64/docs/src/index.md
@@ -1,9 +1,5 @@
 # Base64
 
-```@meta
-DocTestSetup = :(using Base64)
-```
-
 ```@docs
 Base64.Base64
 Base64.Base64EncodePipe
@@ -12,7 +8,3 @@ Base64.Base64DecodePipe
 Base64.base64decode
 Base64.stringmime
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/DelimitedFiles/docs/src/index.md b/stdlib/DelimitedFiles/docs/src/index.md
@@ -1,9 +1,5 @@
 # Delimited Files
 
-```@meta
-DocTestSetup = :(using DelimitedFiles)
-```
-
 ```@docs
 DelimitedFiles.readdlm(::Any, ::AbstractChar, ::Type, ::AbstractChar)
 DelimitedFiles.readdlm(::Any, ::AbstractChar, ::AbstractChar)
@@ -13,7 +9,3 @@ DelimitedFiles.readdlm(::Any, ::Type)
 DelimitedFiles.readdlm(::Any)
 DelimitedFiles.writedlm
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/Distributed/docs/src/index.md b/stdlib/Distributed/docs/src/index.md
@@ -1,9 +1,5 @@
 # Distributed Computing
 
-```@meta
-DocTestSetup = :(using Distributed)
-```
-
 ```@docs
 Distributed.addprocs
 Distributed.nprocs
@@ -70,7 +66,3 @@ Distributed.init_worker
 Distributed.start_worker
 Distributed.process_messages
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/Future/docs/src/index.md b/stdlib/Future/docs/src/index.md
@@ -3,15 +3,7 @@
 The `Future` module implements future behavior of already existing functions,
 which will replace the current version in a future release of Julia.
 
-```@meta
-DocTestSetup = :(using Future)
-```
-
 ```@docs
 Future.copy!
 Future.randjump
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/InteractiveUtils/docs/src/index.md b/stdlib/InteractiveUtils/docs/src/index.md
@@ -1,9 +1,5 @@
 # Interactive Utilities
 
-```@meta
-DocTestSetup = :(using InteractiveUtils)
-```
-
 ```@docs
 InteractiveUtils.apropos
 InteractiveUtils.varinfo
@@ -28,7 +24,3 @@ InteractiveUtils.code_native
 InteractiveUtils.@code_native
 InteractiveUtils.clipboard
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/LibGit2/docs/src/index.md b/stdlib/LibGit2/docs/src/index.md
@@ -1,9 +1,5 @@
 # LibGit2
 
-```@meta
-DocTestSetup = :(using LibGit2)
-```
-
 The LibGit2 module provides bindings to [libgit2](https://libgit2.org/), a portable C library that
 implements core functionality for the [Git](https://git-scm.com/) version control system.
 These bindings are currently used to power Julia's package manager.
@@ -163,7 +159,3 @@ LibGit2.CredentialPayload
 LibGit2.approve
 LibGit2.reject
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/LinearAlgebra/src/generic.jl b/stdlib/LinearAlgebra/src/generic.jl
@@ -1415,9 +1415,9 @@ Currently supports only numeric leaf elements.
 ```jldoctest
 julia> a = [[1,2, [3,4]], 5.0, [6im, [7.0, 8.0]]]
 3-element Array{Any,1}:
-  Any[1,2,[3,4]]
+  Any[1, 2, [3, 4]]
  5.0
-  Any[0+6im,[7.0,8.0]]
+  Any[0 + 6im, [7.0, 8.0]]
 
 julia> LinearAlgebra.promote_leaf_eltypes(a)
 Complex{Float64}

diff --git a/stdlib/Mmap/docs/src/index.md b/stdlib/Mmap/docs/src/index.md
@@ -1,15 +1,7 @@
 # Memory-mapped I/O
 
-```@meta
-DocTestSetup = :(using Mmap)
-```
-
 ```@docs
 Mmap.Anonymous
 Mmap.mmap
 Mmap.sync!
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/Printf/docs/src/index.md b/stdlib/Printf/docs/src/index.md
@@ -1,14 +1,6 @@
 # Printf
 
-```@meta
-DocTestSetup = :(using Printf)
-```
-
 ```@docs
 Printf.@printf
 Printf.@sprintf
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/Sockets/docs/src/index.md b/stdlib/Sockets/docs/src/index.md
@@ -1,9 +1,5 @@
 # Sockets
 
-```@meta
-DocTestSetup = :(using Sockets)
-```
-
 ```@docs
 Sockets.Sockets
 Sockets.connect(::TCPSocket, ::Integer)
@@ -33,7 +29,3 @@ Sockets.setopt
 Sockets.nagle
 Sockets.quickack
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/Statistics/docs/src/index.md b/stdlib/Statistics/docs/src/index.md
@@ -1,9 +1,5 @@
 # Statistics
 
-```@meta
-DocTestSetup = :(using Statistics)
-```
-
 The Statistics module contains basic statistics functionality.
 
 ```@docs
@@ -21,7 +17,3 @@ Statistics.middle
 Statistics.quantile!
 Statistics.quantile
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/UUIDs/docs/src/index.md b/stdlib/UUIDs/docs/src/index.md
@@ -1,16 +1,8 @@
 # UUIDs
 
-```@meta
-DocTestSetup = :(using UUIDs, Random)
-```
-
 ```@docs
 UUIDs.uuid1
 UUIDs.uuid4
 UUIDs.uuid5
 UUIDs.uuid_version
 ```
-
-```@meta
-DocTestSetup = nothing
-```
diff --git a/stdlib/Unicode/docs/src/index.md b/stdlib/Unicode/docs/src/index.md
@@ -1,15 +1,7 @@
 # Unicode
 
-```@meta
-DocTestSetup = :(using Unicode)
-```
-
 ```@docs
 Unicode.isassigned
 Unicode.normalize
 Unicode.graphemes
 ```
-
-```@meta
-DocTestSetup = nothing
-```