Add configurable timeout for linkcheck (#1295)

CHANGELOG.md

@@ -8,6 +8,10 @@
 
 * ![Enhancement][badge-enhancement] The first link fragment on each page now omits the number; before the rendering resulted in: `#foobar-1`, `#foobar-2`, and now: `#foobar`, `#foobar-2`. For backwards compatibility the old fragments are also inserted such that old links will still point to the same location. ([#1292][github-1292])
 
+## Version `v0.24.10`
+
+* ![Enhancement][badge-enhancement] The `curl` timeout when checking remote links is now configurable with the `linkcheck_timeout` keyword. ([#1057][github-1057], [#1295][github-1295])
+
 ## Version `v0.24.9`
 
 * ![Bugfix][badge-bugfix] Canonical URLs are now properly prettified (e.g. `/path/` instead of `/path/index.html`) when using `prettyurls=true`. ([#1293][github-1293])
@@ -500,6 +504,7 @@
 [github-1046]: https://github.com/JuliaDocs/Documenter.jl/issues/1046
 [github-1047]: https://github.com/JuliaDocs/Documenter.jl/pull/1047
 [github-1054]: https://github.com/JuliaDocs/Documenter.jl/pull/1054
+[github-1057]: https://github.com/JuliaDocs/Documenter.jl/issues/1057
 [github-1061]: https://github.com/JuliaDocs/Documenter.jl/pull/1061
 [github-1062]: https://github.com/JuliaDocs/Documenter.jl/pull/1062
 [github-1066]: https://github.com/JuliaDocs/Documenter.jl/pull/1066
@@ -551,6 +556,7 @@
 [github-1285]: https://github.com/JuliaDocs/Documenter.jl/pull/1285
 [github-1292]: https://github.com/JuliaDocs/Documenter.jl/pull/1292
 [github-1293]: https://github.com/JuliaDocs/Documenter.jl/pull/1293
+[github-1295]: https://github.com/JuliaDocs/Documenter.jl/pull/1295
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

src/DocChecks.jl

@@ -193,8 +193,9 @@ function linkcheck(link::Markdown.Link, doc::Documents.Document; method::Symbol=
     end
 
     if !haskey(doc.internal.locallinks, link)
+        timeout = doc.user.linkcheck_timeout
         null_file = @static Sys.iswindows() ? "nul" : "/dev/null"
-        cmd = `curl $(method === :HEAD ? "-sI" : "-s") --proto =http,https,ftp,ftps $(link.url) --max-time 10 -o $null_file --write-out "%{http_code} %{url_effective} %{redirect_url}"`
+        cmd = `curl $(method === :HEAD ? "-sI" : "-s") --proto =http,https,ftp,ftps $(link.url) --max-time $timeout -o $null_file --write-out "%{http_code} %{url_effective} %{redirect_url}"`
 
         local result
         try

src/Documenter.jl

@@ -199,6 +199,9 @@ will fail if there are any broken (400+ status code) links. Default: `false`.
 be a list of strings (which get matched exactly) or `Regex` objects. By default nothing is
 ignored.
 
+**`linkcheck_timeout`** configures how long `curl` waits (in seconds) for a link request to
+return a response before giving up. The default is 10 seconds.
+
 **`strict`** -- [`makedocs`](@ref) fails the build right before rendering if it encountered
 any errors with the document in the previous build phases.
 

src/Documents.jl

@@ -220,6 +220,7 @@ struct User
     doctest :: Union{Bool,Symbol} # Run doctests?
     linkcheck::Bool           # Check external links..
     linkcheck_ignore::Vector{Union{String,Regex}}  # ..and then ignore (some of) them.
+    linkcheck_timeout::Real   # ..but only wait this many seconds for each one.
     checkdocs::Symbol         # Check objects missing from `@docs` blocks. `:none`, `:exports`, or `:all`.
     doctestfilters::Vector{Regex} # Filtering for doctests
     strict::Bool              # Throw an exception when any warnings are encountered.
@@ -273,6 +274,7 @@ function Document(plugins = nothing;
         doctest  :: Union{Bool,Symbol} = true,
         linkcheck:: Bool             = false,
         linkcheck_ignore :: Vector   = [],
+        linkcheck_timeout :: Real    = 10,
         checkdocs::Symbol            = :all,
         doctestfilters::Vector{Regex}= Regex[],
         strict::Bool                 = false,
@@ -306,6 +308,7 @@ function Document(plugins = nothing;
         doctest,
         linkcheck,
         linkcheck_ignore,
+        linkcheck_timeout,
         checkdocs,
         doctestfilters,
         strict,

test/docchecks.jl

@@ -7,7 +7,6 @@ using Documenter.DocChecks: linkcheck
 using Documenter.Documents
 
 @testset "DocChecks" begin
-    # The linkcheck tests are currently not reliable on CI, so they are disabled.
     @testset "linkcheck" begin
         src = md"""
             [HTTP (HTTP/1.1) success](http://www.google.com)
@@ -19,9 +18,9 @@ using Documenter.Documents
             """
 
         Documents.walk(Dict{Symbol, Any}(), src) do block
-            doc = Documents.Document(; linkcheck=true)
+            doc = Documents.Document(; linkcheck=true, linkcheck_timeout=20)
             result = linkcheck(block, doc)
-            @test_skip doc.internal.errors == Set{Symbol}()
+            @test doc.internal.errors == Set{Symbol}()
             result
         end
 
@@ -30,7 +29,14 @@ using Documenter.Documents
         Documents.walk(Dict{Symbol, Any}(), src) do block
             linkcheck(block, doc)
         end
-        @test_skip doc.internal.errors == Set{Symbol}([:linkcheck])
+        @test doc.internal.errors == Set{Symbol}([:linkcheck])
+
+        src = Markdown.parse("[Timeout](http://httpbin.org/delay/3)")
+        doc = Documents.Document(; linkcheck=true, linkcheck_timeout=0.1)
+        Documents.walk(Dict{Symbol, Any}(), src) do block
+            linkcheck(block, doc)
+        end
+        @test doc.internal.errors == Set{Symbol}([:linkcheck])
     end
 end