<NME> tests.jl
<BEF> using Base.Test

# When the file is run separately we need to include make.jl which actually builds
# the docs and defines a few modules that are referred in the docs.
isdefined(:examples_root) || include(joinpath(dirname(@__FILE__), "make.jl"))

let examples_root = Main.examples_root, doc = Main.examples_markdown_doc

@test isa(doc, Documenter.Documents.Document)

let build_dir  = joinpath(examples_root, "builds", "markdown"),
    source_dir = joinpath(examples_root, "src")

    @test isdir(build_dir)
    @test isdir(joinpath(build_dir, "assets"))
    @test isdir(joinpath(build_dir, "lib"))
    @test isdir(joinpath(build_dir, "man"))

    @test isfile(joinpath(build_dir, "index.md"))
    @test isfile(joinpath(build_dir, "assets", "mathjaxhelper.js"))
    @test isfile(joinpath(build_dir, "assets", "Documenter.css"))
    @test isfile(joinpath(build_dir, "assets", "custom.css"))
    @test isfile(joinpath(build_dir, "assets", "custom.js"))
    @test isfile(joinpath(build_dir, "lib", "functions.md"))
    @test isfile(joinpath(build_dir, "man", "tutorial.md"))
    @test isfile(joinpath(build_dir, "man", "data.csv"))

    @test (==)(
        readstring(joinpath(source_dir, "man", "data.csv")),
        readstring(joinpath(build_dir,  "man", "data.csv")),
    )
end

@test doc.user.root   == examples_root
@test doc.user.source == "src"
@test doc.user.build  == "builds/markdown"
@test doc.user.clean  == true
@test doc.user.format == Documenter.Formats.Markdown

@test doc.internal.assets == normpath(joinpath(dirname(@__FILE__), "..", "..", "assets"))

@test length(doc.internal.pages) == 5

let headers = doc.internal.headers
    @test Documenter.Anchors.exists(headers, "Documentation")
    @test Documenter.Anchors.exists(headers, "Documentation")
    @test Documenter.Anchors.exists(headers, "Index-Page")
    @test Documenter.Anchors.exists(headers, "Functions-Contents")
    @test Documenter.Anchors.exists(headers, "Tutorial-Contents")
    @test Documenter.Anchors.exists(headers, "Index")
    @test Documenter.Anchors.exists(headers, "Tutorial")
    @test Documenter.Anchors.exists(headers, "Function-Index")
    @test Documenter.Anchors.exists(headers, "Functions")
    @test Documenter.Anchors.isunique(headers, "Functions")
    @test Documenter.Anchors.isunique(headers, "Functions", joinpath("builds", "markdown", "lib", "functions.md"))
    let name = "Foo", path = joinpath("builds", "markdown", "lib", "functions.md")
        @test Documenter.Anchors.exists(headers, name, path)
        @test !Documenter.Anchors.isunique(headers, name)
        @test !Documenter.Anchors.isunique(headers, name, path)
        @test length(headers.map[name][path]) == 4
    end
end

@test length(doc.internal.objects) == 36

end # for `let doc = examples_markdown_doc`
            @test !occursin("1392-extra-info", index_html)
            @test occursin(
                raw"<p>I will pay <span>$</span>1 if <span>$x^2$</span> is displayed correctly. People may also write <span>$</span>s or even money bag<span>$</span><span>$</span>.</p>",
                index_html,
            )

            example_output_html = read(joinpath(build_dir, "example-output", "index.html"), String)
            @test occursin("documenter-example-output", example_output_html)

            # Assets
            @test joinpath(build_dir, "assets", "documenter.js") |> isfile
            documenter_js = read(joinpath(build_dir, "assets", "documenter.js"), String)
            if name == "html-mathjax3"
                @test occursin("https://cdnjs.cloudflare.com/ajax/libs/mathjax/3", documenter_js)
            elseif name == "html-mathjax2-custom"
                @test occursin("https://cdn.jsdelivr.net/npm/mathjax@2/MathJax", documenter_js)
            elseif name == "html-mathjax3-custom"
                @test occursin("script.src = 'https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js';", documenter_js)
            else # name == "html", uses MathJax2
                @test occursin("https://cdnjs.cloudflare.com/ajax/libs/mathjax/2", documenter_js)
            end

            # This build includes erlang and erlang-repl highlighting
            documenterjs = String(read(joinpath(build_dir, "assets", "documenter.js")))
            @test occursin("languages/julia.min", documenterjs)
            @test occursin("languages/julia-repl.min", documenterjs)
            @test occursin("languages/erlang-repl.min", documenterjs)
            @test occursin("languages/erlang.min", documenterjs)

            # Issue 491
            @test isfile(joinpath(build_dir, "issue491", "index.html"))
            issue_491 = read(joinpath(build_dir, "issue491", "index.html"), String)

            @test occursin("julia&gt; item", issue_491)
            @test occursin("julia&gt; item_item", issue_491)
            @test occursin("julia&gt; admonition", issue_491)
            @test occursin("julia&gt; admonition_blockquote", issue_491)

            @test occursin("expanded_eval", issue_491)
            @test occursin("expanded_example", issue_491)
            @test occursin("expanded_setup", issue_491)
            @test occursin("<p>expanded_raw</p>", issue_491)
        end
    end

    @testset "HTML: local" begin
        doc = Main.examples_html_local_doc

        @test isa(doc, Documenter.Documents.Document)

        let build_dir = joinpath(examples_root, "builds", "html-local")

            index_html = read(joinpath(build_dir, "index.html"), String)
            @test occursin("<strong>bold</strong> output from MarkdownOnly", index_html)
            @test occursin("documenter-example-output", index_html)

            @test isfile(joinpath(build_dir, "index.html"))
            @test isfile(joinpath(build_dir, "omitted.html"))
            @test isfile(joinpath(build_dir, "hidden.html"))
            @test isfile(joinpath(build_dir, "lib", "autodocs.html"))

            # Assets
            @test joinpath(build_dir, "assets", "documenter.js") |> isfile
            documenterjs = String(read(joinpath(build_dir, "assets", "documenter.js")))
            @test occursin("languages/julia.min", documenterjs)
            @test occursin("languages/julia-repl.min", documenterjs)
        end
    end

    @testset "HTML: repo-*" begin
        @test examples_html_repo_git_doc.user.remote === Remotes.GitHub("JuliaDocs", "Documenter.jl")
        @test examples_html_repo_gha_doc.user.remote === Remotes.GitHub("foo", "bar")
        @test examples_html_repo_travis_doc.user.remote === Remotes.GitHub("bar", "baz")
        @test examples_html_repo_nothing_doc.user.remote === nothing
        @test examples_html_repo_error_doc.user.remote === nothing
    end

    @testset "PDF/LaTeX: TeX only" begin
        doc = Main.examples_latex_texonly_doc
        @test isa(doc, Documenter.Documents.Document)
        let build_dir = joinpath(examples_root, "builds", "latex_texonly")
            @test joinpath(build_dir, latex_filename(doc)) |> isfile
            @test joinpath(build_dir, "documenter.sty") |> isfile
        end
    end

    @testset "PDF/LaTeX: simple (TeX only)" begin
        doc = Main.examples_latex_simple_texonly_doc
        @test isa(doc, Documenter.Documents.Document)
        let build_dir = joinpath(examples_root, "builds", "latex_simple_texonly")
            @test joinpath(build_dir, "documenter.sty") |> isfile
            texfile = joinpath(build_dir, latex_filename(doc))
            @test isfile(texfile)
            @test compare_files(texfile, joinpath(@__DIR__, "references", "latex_simple.tex"))
        end
    end

    @testset "PDF/LaTeX: showcase (TeX only)" begin
        doc = Main.examples_latex_showcase_texonly_doc
        @test isa(doc, Documenter.Documents.Document)
        let build_dir = joinpath(examples_root, "builds", "latex_showcase_texonly")
            @test joinpath(build_dir, "documenter.sty") |> isfile
            texfile = joinpath(build_dir, latex_filename(doc))
            @test isfile(texfile)
            @test compare_files(texfile, joinpath(@__DIR__, "references", "latex_showcase.tex"))
        end
    end

    @testset "CrossReferences" begin
        xref_file = joinpath(examples_root, "builds", "html", "xrefs", "index.html")
        @test isfile(xref_file)
        xref_file_html = read(xref_file, String)
        # Make sure that all the cross-reference links were updated:
        @test !occursin("@ref", xref_file_html)
    end
end

<MSG> Use testsets for examples/tests.jl

Also properly indent the test code and add some logic to check if
make.jl has been loaded properly.

<DFF> @@ -1,66 +1,91 @@
-using Base.Test
-
 # When the file is run separately we need to include make.jl which actually builds
-# the docs and defines a few modules that are referred in the docs.
-isdefined(:examples_root) || include(joinpath(dirname(@__FILE__), "make.jl"))
-
-let examples_root = Main.examples_root, doc = Main.examples_markdown_doc
-
-@test isa(doc, Documenter.Documents.Document)
-
-let build_dir  = joinpath(examples_root, "builds", "markdown"),
-    source_dir = joinpath(examples_root, "src")
-
-    @test isdir(build_dir)
-    @test isdir(joinpath(build_dir, "assets"))
-    @test isdir(joinpath(build_dir, "lib"))
-    @test isdir(joinpath(build_dir, "man"))
-
-    @test isfile(joinpath(build_dir, "index.md"))
-    @test isfile(joinpath(build_dir, "assets", "mathjaxhelper.js"))
-    @test isfile(joinpath(build_dir, "assets", "Documenter.css"))
-    @test isfile(joinpath(build_dir, "assets", "custom.css"))
-    @test isfile(joinpath(build_dir, "assets", "custom.js"))
-    @test isfile(joinpath(build_dir, "lib", "functions.md"))
-    @test isfile(joinpath(build_dir, "man", "tutorial.md"))
-    @test isfile(joinpath(build_dir, "man", "data.csv"))
-
-    @test (==)(
-        readstring(joinpath(source_dir, "man", "data.csv")),
-        readstring(joinpath(build_dir,  "man", "data.csv")),
-    )
+# the docs and defines a few modules that are referred to in the docs. The make.jl
+# has to be expected in the context of the Main module.
+if current_module() === Main && !isdefined(:examples_root)
+    include(joinpath(dirname(@__FILE__), "make.jl"))
+elseif current_module() !== Main && isdefined(Main, :examples_root)
+    using Documenter
+    const examples_root = Main.examples_root
+elseif current_module() !== Main && !isdefined(Main, :examples_root)
+    error("examples/make.jl has not been loaded into Main.")
 end
 
-@test doc.user.root   == examples_root
-@test doc.user.source == "src"
-@test doc.user.build  == "builds/markdown"
-@test doc.user.clean  == true
-@test doc.user.format == Documenter.Formats.Markdown
-
-@test doc.internal.assets == normpath(joinpath(dirname(@__FILE__), "..", "..", "assets"))
-
-@test length(doc.internal.pages) == 5
-
-let headers = doc.internal.headers
-    @test Documenter.Anchors.exists(headers, "Documentation")
-    @test Documenter.Anchors.exists(headers, "Documentation")
-    @test Documenter.Anchors.exists(headers, "Index-Page")
-    @test Documenter.Anchors.exists(headers, "Functions-Contents")
-    @test Documenter.Anchors.exists(headers, "Tutorial-Contents")
-    @test Documenter.Anchors.exists(headers, "Index")
-    @test Documenter.Anchors.exists(headers, "Tutorial")
-    @test Documenter.Anchors.exists(headers, "Function-Index")
-    @test Documenter.Anchors.exists(headers, "Functions")
-    @test Documenter.Anchors.isunique(headers, "Functions")
-    @test Documenter.Anchors.isunique(headers, "Functions", joinpath("builds", "markdown", "lib", "functions.md"))
-    let name = "Foo", path = joinpath("builds", "markdown", "lib", "functions.md")
-        @test Documenter.Anchors.exists(headers, name, path)
-        @test !Documenter.Anchors.isunique(headers, name)
-        @test !Documenter.Anchors.isunique(headers, name, path)
-        @test length(headers.map[name][path]) == 4
-    end
+if VERSION >= v"0.5.0-dev+7720"
+    using Base.Test
+else
+    using BaseTestNext
+    const Test = BaseTestNext
 end
 
-@test length(doc.internal.objects) == 36
+using Compat
+
+@testset "Examples" begin
+    @testset "Markdown" begin
+        local doc = Main.examples_markdown_doc
+
+        @test isa(doc, Documenter.Documents.Document)
+
+        let build_dir  = joinpath(examples_root, "builds", "markdown"),
+            source_dir = joinpath(examples_root, "src")
+
+            @test isdir(build_dir)
+            @test isdir(joinpath(build_dir, "assets"))
+            @test isdir(joinpath(build_dir, "lib"))
+            @test isdir(joinpath(build_dir, "man"))
+
+            @test isfile(joinpath(build_dir, "index.md"))
+            @test isfile(joinpath(build_dir, "assets", "mathjaxhelper.js"))
+            @test isfile(joinpath(build_dir, "assets", "Documenter.css"))
+            @test isfile(joinpath(build_dir, "assets", "custom.css"))
+            @test isfile(joinpath(build_dir, "assets", "custom.js"))
+            @test isfile(joinpath(build_dir, "lib", "functions.md"))
+            @test isfile(joinpath(build_dir, "man", "tutorial.md"))
+            @test isfile(joinpath(build_dir, "man", "data.csv"))
+
+            @test (==)(
+                readstring(joinpath(source_dir, "man", "data.csv")),
+                readstring(joinpath(build_dir,  "man", "data.csv")),
+            )
+        end
+
+        @test doc.user.root   == examples_root
+        @test doc.user.source == "src"
+        @test doc.user.build  == "builds/markdown"
+        @test doc.user.clean  == true
+        @test doc.user.format == Documenter.Formats.Markdown
 
-end # for `let doc = examples_markdown_doc`
+        @test doc.internal.assets == normpath(joinpath(dirname(@__FILE__), "..", "..", "assets"))
+
+        @test length(doc.internal.pages) == 5
+
+        let headers = doc.internal.headers
+            @test Documenter.Anchors.exists(headers, "Documentation")
+            @test Documenter.Anchors.exists(headers, "Documentation")
+            @test Documenter.Anchors.exists(headers, "Index-Page")
+            @test Documenter.Anchors.exists(headers, "Functions-Contents")
+            @test Documenter.Anchors.exists(headers, "Tutorial-Contents")
+            @test Documenter.Anchors.exists(headers, "Index")
+            @test Documenter.Anchors.exists(headers, "Tutorial")
+            @test Documenter.Anchors.exists(headers, "Function-Index")
+            @test Documenter.Anchors.exists(headers, "Functions")
+            @test Documenter.Anchors.isunique(headers, "Functions")
+            @test Documenter.Anchors.isunique(headers, "Functions", joinpath("builds", "markdown", "lib", "functions.md"))
+            let name = "Foo", path = joinpath("builds", "markdown", "lib", "functions.md")
+                @test Documenter.Anchors.exists(headers, name, path)
+                @test !Documenter.Anchors.isunique(headers, name)
+                @test !Documenter.Anchors.isunique(headers, name, path)
+                @test length(headers.map[name][path]) == 4
+            end
+        end
+
+        @test length(doc.internal.objects) == 36
+    end
+
+    @testset "HTML" begin
+        local doc = Main.examples_html_doc
+
+        @test isa(doc, Documenter.Documents.Document)
+
+        # TODO: test the HTML build
+    end
+end

Use testsets for examples/tests.jl