|
| 1 | +module WarningTests |
| 2 | + |
| 3 | +# Test warnings |
| 4 | +# see https://github.com/JuliaDocs/Documenter.jl/issues/2805 |
| 5 | + |
| 6 | +using Test |
| 7 | +using Documenter |
| 8 | +using IOCapture |
| 9 | + |
| 10 | +isdefined(Main, :Documenter) || @eval Main import Documenter |
| 11 | + |
| 12 | +function run_warnings_test(name::String) |
| 13 | + captured = IOCapture.capture() do |
| 14 | + makedocs(; |
| 15 | + sitename = name, |
| 16 | + pages = ["index.md", "$name.md"], |
| 17 | + pagesonly = true, |
| 18 | + warnonly = true, |
| 19 | + format = Documenter.HTML( |
| 20 | + prettyurls = false, |
| 21 | + inventory_version = "", |
| 22 | + ), |
| 23 | + ) |
| 24 | + end |
| 25 | + @assert isnothing(captured.value) |
| 26 | + |
| 27 | + # sanitize the output |
| 28 | + output = captured.output |
| 29 | + output = replace(output, r"\@ Documenter.*" => "@ Documenter") |
| 30 | + output = replace(output, "src\\" => "src/") |
| 31 | + return print(output) |
| 32 | +end |
| 33 | + |
| 34 | +@doc raw""" |
| 35 | +```jldoctest; setup=:(using ..WarningTests) |
| 36 | +julia> WarningTests.run_warnings_test("at-docs") |
| 37 | +[ Info: SetupBuildDirectory: setting up build directory. |
| 38 | +[ Info: Doctest: running doctests. |
| 39 | +[ Info: ExpandTemplates: expanding markdown templates. |
| 40 | +┌ Warning: undefined binding 'Base.nonsenseBindingThatDoesNotExist' in `@docs` block in src/at-docs.md:4-6 |
| 41 | +│ ```@docs |
| 42 | +│ Base.nonsenseBindingThatDoesNotExist() |
| 43 | +│ ``` |
| 44 | +└ @ Documenter |
| 45 | +┌ Warning: no docs found for 'Base.sin()' in `@docs` block in src/at-docs.md:9-11 |
| 46 | +│ ```@docs |
| 47 | +│ Base.sin() |
| 48 | +│ ``` |
| 49 | +└ @ Documenter |
| 50 | +┌ Warning: failed to evaluate `Base.sin(::NonsenseTypeThatDoesNotExist)` in `@docs` block in src/at-docs.md:14-16 |
| 51 | +│ ```@docs |
| 52 | +│ Base.sin(::NonsenseTypeThatDoesNotExist) |
| 53 | +│ ``` |
| 54 | +│ exception = |
| 55 | +│ UndefVarError: `NonsenseTypeThatDoesNotExist` not defined in `Main` |
| 56 | +│ Suggestion: check for spelling errors or missing imports. |
| 57 | +└ @ Documenter |
| 58 | +[ Info: CrossReferences: building cross-references. |
| 59 | +[ Info: CheckDocument: running document checks. |
| 60 | +[ Info: Populate: populating indices. |
| 61 | +[ Info: RenderDocument: rendering document. |
| 62 | +[ Info: HTMLWriter: rendering HTML pages. |
| 63 | +``` |
| 64 | +""" |
| 65 | +module AtDocsWarningTests end |
| 66 | + |
| 67 | +fixtests = haskey(ENV, "DOCUMENTER_FIXTESTS") |
| 68 | + |
| 69 | +# run the doctests in Julia >= 1.10 (some outputs have minor difference in |
| 70 | +# older Julia versions, and it just doesn't seem worth the trouble of coping |
| 71 | +# with that "properly") |
| 72 | +VERSION >= v"1.10" && makedocs(; |
| 73 | + sitename = "", |
| 74 | + doctest = fixtests ? :fix : :only, |
| 75 | + modules = [WarningTests], |
| 76 | + remotes = nothing, |
| 77 | +) |
| 78 | + |
| 79 | +end |
0 commit comments