From 432453119e19bd3d54600ea0ffa23d6b15b54912 Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Thu, 1 Aug 2019 13:11:06 -0400 Subject: [PATCH] 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 --- doc/Manifest.toml | 22 ++++++++++++++-------- doc/make.jl | 8 +++++++- stdlib/Base64/docs/src/index.md | 8 -------- stdlib/DelimitedFiles/docs/src/index.md | 8 -------- stdlib/Distributed/docs/src/index.md | 8 -------- stdlib/Future/docs/src/index.md | 8 -------- stdlib/InteractiveUtils/docs/src/index.md | 8 -------- stdlib/LibGit2/docs/src/index.md | 8 -------- stdlib/LinearAlgebra/src/generic.jl | 4 ++-- stdlib/Mmap/docs/src/index.md | 8 -------- stdlib/Printf/docs/src/index.md | 8 -------- stdlib/Sockets/docs/src/index.md | 8 -------- stdlib/Statistics/docs/src/index.md | 8 -------- stdlib/UUIDs/docs/src/index.md | 8 -------- stdlib/Unicode/docs/src/index.md | 8 -------- 15 files changed, 23 insertions(+), 107 deletions(-) diff --git a/doc/Manifest.toml b/doc/Manifest.toml index 16f331529d58e..b392be3de1666 100644 --- 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 index f98accc184877..178223d6548f4 100644 --- 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 index 163be193979c3..6bc647f8a2e67 100644 --- 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 index 839bdb8f0f0e5..11e24f12ff3c1 100644 --- 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 index 49668bbfe35f2..114ac1683a54a 100644 --- 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 index 8e2ce6772a41a..dcb1a36541b6e 100644 --- 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 index 7e313b8ccd048..4d3a39c9d9e3e 100644 --- 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 index 2eafb77bc87cc..e53a9330cb1d2 100644 --- 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 index 087fa4eefc73a..623b31d65ac62 100644 --- 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 index 9bd623daebdf5..ada88b153de64 100644 --- 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 index de79d5c983eb4..828e527ed0cad 100644 --- 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 index 90acd104182f2..a67d945f16748 100644 --- 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 index 5a684541f015f..426166b3aea19 100644 --- 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 index 4c2f6a5e33c58..1e6c950dd8999 100644 --- 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 index 474629d541be7..aba9d80c3e8b5 100644 --- 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 -```