From 585a9e827f564fb024f1e1f7bb2150efd7db931f Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Thu, 29 Sep 2016 22:44:56 +0200 Subject: [PATCH 01/14] Add a style note on module indentation --- docs/src/man/contributing.md | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/src/man/contributing.md b/docs/src/man/contributing.md index 385aae926b..7731abafd7 100644 --- a/docs/src/man/contributing.md +++ b/docs/src/man/contributing.md @@ -21,6 +21,7 @@ Follow the style of the surrounding text when making changes. When adding new fe ### Julia * 4-space indentation; + * modules spanning entire files should not be indented, but modules that have surrounding code should; * no blank lines at the start or end of files; * do not manually align syntax such as `=` or `::` over adjacent lines; * use `local` to define new local variables so that they are easier to locate; From 9b79f176865cbedb3a9d835fa748d189e3ec2451 Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Thu, 29 Sep 2016 22:25:26 +0200 Subject: [PATCH 02/14] Move test/examples build code Move the code of setting up the modules and building the examples docs under examples/ to test/examples/make.jl. This allows the examples/ to be built without calling the whole runtests.jl file. The pages/* are considered to be part of the examples/. The Mod and AutoDocs modules are now indented to help with readability. Also, the output from the examples/ builds will now be stored under test/examples/builds/, instead of test/examples/build-. --- .gitignore | 2 +- test/examples/make.jl | 108 +++++++++++++++++++++++++++ test/{ => examples}/pages/a.jl | 0 test/{ => examples}/pages/b.jl | 0 test/{ => examples}/pages/c.jl | 0 test/{ => examples}/pages/d.jl | 0 test/{ => examples}/pages/e.jl | 0 test/runtests.jl | 131 +++------------------------------ 8 files changed, 120 insertions(+), 121 deletions(-) create mode 100644 test/examples/make.jl rename test/{ => examples}/pages/a.jl (100%) rename test/{ => examples}/pages/b.jl (100%) rename test/{ => examples}/pages/c.jl (100%) rename test/{ => examples}/pages/d.jl (100%) rename test/{ => examples}/pages/e.jl (100%) diff --git a/.gitignore b/.gitignore index 569b087440..cead08769e 100644 --- a/.gitignore +++ b/.gitignore @@ -2,7 +2,7 @@ *.jl.*.cov *.jl.mem -test/examples/build-* +test/examples/builds/ test/missingdocs/build/ test/errors/build/ docs/build/ diff --git a/test/examples/make.jl b/test/examples/make.jl new file mode 100644 index 0000000000..04ddfed8bf --- /dev/null +++ b/test/examples/make.jl @@ -0,0 +1,108 @@ +# Defines the modules referred to in the example docs (under src/) and then builds them. +# It can be called separately to build the examples/, or as part of the test suite. +# +# It defines a set of variables (`examples_*`) that can be used in the tests. +# The `examples_root` should be used to check whether this file has already been included +# or not and should be kept unique. +isdefined(:examples_root) && error("examples_root is already defined\n$(@__FILE__) included multiple times?") + +# Modules `Mod` and `AutoDocs` +module Mod + """ + func(x) + + [`T`](@ref) + """ + func(x) = x + + """ + T + + [`func(x)`](@ref) + """ + type T end +end + +"`AutoDocs` module." +module AutoDocs + module Pages + include("pages/a.jl") + include("pages/b.jl") + include("pages/c.jl") + include("pages/d.jl") + include("pages/e.jl") + end + + "Function `f`." + f(x) = x + + "Constant `K`." + const K = 1 + + "Type `T`." + type T end + + "Macro `@m`." + macro m() end + + "Module `A`." + module A + "Function `A.f`." + f(x) = x + + "Constant `A.K`." + const K = 1 + + "Type `B.T`." + type T end + + "Macro `B.@m`." + macro m() end + end + + "Module `B`." + module B + "Function `B.f`." + f(x) = x + + "Constant `B.K`." + const K = 1 + + "Type `B.T`." + type T end + + "Macro `B.@m`." + macro m() end + end +end + +# Build example docs +using Documenter + +const examples_root = dirname(@__FILE__) + +info("Building mock package docs: MarkdownWriter") +examples_markdown_doc = makedocs( + debug = true, + root = examples_root, + build = "builds/markdown", +) + +info("Building mock package docs: HTMLWriter") +examples_html_doc = makedocs( + debug = true, + root = examples_root, + build = "builds/html", + format = Documenter.Formats.HTML, + sitename = "Documenter example", + pages = Any[ + "Home" => "index.md", + "Manual" => [ + "man/tutorial.md", + ], + "Library" => [ + "lib/functions.md", + "lib/autodocs.md", + ] + ] +) diff --git a/test/pages/a.jl b/test/examples/pages/a.jl similarity index 100% rename from test/pages/a.jl rename to test/examples/pages/a.jl diff --git a/test/pages/b.jl b/test/examples/pages/b.jl similarity index 100% rename from test/pages/b.jl rename to test/examples/pages/b.jl diff --git a/test/pages/c.jl b/test/examples/pages/c.jl similarity index 100% rename from test/pages/c.jl rename to test/examples/pages/c.jl diff --git a/test/pages/d.jl b/test/examples/pages/d.jl similarity index 100% rename from test/pages/d.jl rename to test/examples/pages/d.jl diff --git a/test/pages/e.jl b/test/examples/pages/e.jl similarity index 100% rename from test/pages/e.jl rename to test/examples/pages/e.jl diff --git a/test/runtests.jl b/test/runtests.jl index 9a89cdd7b3..41ec49fbcf 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -1,90 +1,8 @@ # Build the real docs first. include(joinpath(dirname(@__FILE__), "..", "docs", "make.jl")) -# docs module -# =========== - -module Mod - -""" - func(x) - -[`T`](@ref) -""" -func(x) = x - -""" - T - -[`func(x)`](@ref) -""" -type T end - -end - -# autodocs module -# =============== - -"`AutoDocs` module." -module AutoDocs - -module Pages - -include("pages/a.jl") -include("pages/b.jl") -include("pages/c.jl") -include("pages/d.jl") -include("pages/e.jl") - -end - -"Function `f`." -f(x) = x - -"Constant `K`." -const K = 1 - -"Type `T`." -type T end - -"Macro `@m`." -macro m() end - -"Module `A`." -module A - -"Function `A.f`." -f(x) = x - -"Constant `A.K`." -const K = 1 - -"Type `B.T`." -type T end - -"Macro `B.@m`." -macro m() end - -end - -"Module `B`." -module B - -"Function `B.f`." -f(x) = x - -"Constant `B.K`." -const K = 1 - -"Type `B.T`." -type T end - -"Macro `B.@m`." -macro m() end - -end - -end +# Build the example docs +include(joinpath(dirname(@__FILE__), "examples", "make.jl")) module MissingDocs @@ -380,25 +298,15 @@ for sym in [:none, :exports] ) end -# setup -# ===== - -const example_root = joinpath(dirname(@__FILE__), "examples") - -info("Building mock package docs: MarkdownWriter") -doc = makedocs( - debug = true, - root = example_root, - build = "build-markdown", -) - # tests # ===== +let examples_root = Main.examples_root, doc = Main.examples_markdown_doc + @test isa(doc, Documenter.Documents.Document) -let build_dir = joinpath(example_root, "build-markdown"), - source_dir = joinpath(example_root, "src") +let build_dir = joinpath(examples_root, "builds", "markdown"), + source_dir = joinpath(examples_root, "src") @test isdir(build_dir) @test isdir(joinpath(build_dir, "assets")) @@ -420,9 +328,9 @@ let build_dir = joinpath(example_root, "build-markdown"), ) end -@test doc.user.root == example_root +@test doc.user.root == examples_root @test doc.user.source == "src" -@test doc.user.build == "build-markdown" +@test doc.user.build == "builds/markdown" @test doc.user.clean == true @test doc.user.format == Documenter.Formats.Markdown @@ -441,8 +349,8 @@ let headers = doc.internal.headers @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("build-markdown", "lib", "functions.md")) - let name = "Foo", path = joinpath("build-markdown", "lib", "functions.md") + @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) @@ -452,24 +360,7 @@ end @test length(doc.internal.objects) == 36 -info("Building mock package docs: HTMLWriter") -doc = makedocs( - debug = true, - root = example_root, - build = "build-html", - format = Documenter.Formats.HTML, - sitename = "Documenter example", - pages = Any[ - "Home" => "index.md", - "Manual" => [ - "man/tutorial.md", - ], - "Library" => [ - "lib/functions.md", - "lib/autodocs.md", - ] - ] -) +end # for `let doc = examples_markdown_doc` # Documenter package docs: From 172e1c71933cb7b398f0c93c38927fa77227a736 Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Thu, 29 Sep 2016 23:27:45 +0200 Subject: [PATCH 03/14] Move examples/ tests to a separate file Moves the tests of the examples/ build to examples/tests.jl. The tests can be run separately as well. --- test/examples/tests.jl | 66 ++++++++++++++++++++++++++++++++++++++++++ test/runtests.jl | 64 +--------------------------------------- 2 files changed, 67 insertions(+), 63 deletions(-) create mode 100644 test/examples/tests.jl diff --git a/test/examples/tests.jl b/test/examples/tests.jl new file mode 100644 index 0000000000..e3f92763ff --- /dev/null +++ b/test/examples/tests.jl @@ -0,0 +1,66 @@ +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` diff --git a/test/runtests.jl b/test/runtests.jl index 41ec49fbcf..ee4639fc17 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -298,69 +298,7 @@ for sym in [:none, :exports] ) end -# tests -# ===== - -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` +include(joinpath(dirname(@__FILE__), "examples", "tests.jl")) # Documenter package docs: From 051af35f98a21c4604f6b88f4c2ff11a0ec71455 Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Thu, 29 Sep 2016 23:43:37 +0200 Subject: [PATCH 04/14] Move missing docs tests to a separate file --- test/missingdocs/make.jl | 23 +++++++++++++++++++++++ test/runtests.jl | 26 ++------------------------ 2 files changed, 25 insertions(+), 24 deletions(-) create mode 100644 test/missingdocs/make.jl diff --git a/test/missingdocs/make.jl b/test/missingdocs/make.jl new file mode 100644 index 0000000000..58cfc350cd --- /dev/null +++ b/test/missingdocs/make.jl @@ -0,0 +1,23 @@ +module MissingDocs + export f + + "exported" + f(x) = x + + "unexported" + g(x) = x +end + +using Documenter + +for sym in [:none, :exports] + makedocs( + root = dirname(@__FILE__), + source = joinpath("src", string(sym)), + build = joinpath("build", string(sym)), + modules = MissingDocs, + checkdocs = sym, + format = Documenter.Formats.HTML, + sitename = "MissingDocs Checks", + ) +end diff --git a/test/runtests.jl b/test/runtests.jl index ee4639fc17..87d989d159 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -4,16 +4,8 @@ include(joinpath(dirname(@__FILE__), "..", "docs", "make.jl")) # Build the example docs include(joinpath(dirname(@__FILE__), "examples", "make.jl")) -module MissingDocs - -export f -"exported" -f(x) = x - -"unexported" -g(x) = x - -end +# Test missing docs +include(joinpath(dirname(@__FILE__), "missingdocs", "make.jl")) # tests module # ============ @@ -284,20 +276,6 @@ println("="^50) # Mock package docs: -## Missing Docs. - -for sym in [:none, :exports] - makedocs( - root = joinpath(dirname(@__FILE__), "missingdocs"), - source = joinpath("src", string(sym)), - build = joinpath("build", string(sym)), - modules = Main.MissingDocs, - checkdocs = sym, - format = Documenter.Formats.HTML, - sitename = "MissingDocs Checks", - ) -end - include(joinpath(dirname(@__FILE__), "examples", "tests.jl")) # Documenter package docs: From 9ed346d9a4a782b1bdf622b1dc7882120486914c Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Sun, 2 Oct 2016 19:23:13 +0200 Subject: [PATCH 05/14] Indent submodules of Tests in runtests.jl --- test/runtests.jl | 209 +++++++++++++++++++++++------------------------ 1 file changed, 101 insertions(+), 108 deletions(-) diff --git a/test/runtests.jl b/test/runtests.jl index 87d989d159..ad9ad965d2 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -20,24 +20,21 @@ using Compat # Unit tests for module internals. module UnitTests + module SubModule end -module SubModule end - -# Does `submodules` collect *all* the submodules? -module A -module B -module C -module D -end -end -end -end - -type T end + # Does `submodules` collect *all* the submodules? + module A + module B + module C + module D end + end + end + end -"Documenter unit tests." -Base.length(::T) = 1 + type T end + "Documenter unit tests." + Base.length(::T) = 1 end let doc = @doc(length) @@ -155,115 +152,111 @@ end ## DOM Tests. module DOMTests + using Base.Test + import Documenter.Utilities.DOM: DOM, @tags -using Base.Test -import Documenter.Utilities.DOM: DOM, @tags - -@tags div ul li p + @tags div ul li p -for tag in (:div, :ul, :li, :p) - TAG = getfield(current_module(), tag) - @test isdefined(tag) - @test isa(TAG, DOM.Tag) - @test TAG.name === tag -end + for tag in (:div, :ul, :li, :p) + TAG = getfield(current_module(), tag) + @test isdefined(tag) + @test isa(TAG, DOM.Tag) + @test TAG.name === tag + end -@test div().name === :div -@test div().text == "" -@test isempty(div().nodes) -@test isempty(div().attributes) - -@test div("...").name === :div -@test div("...").text == "" -@test length(div("...").nodes) === 1 -@test div("...").nodes[1].text == "..." -@test div("...").nodes[1].name === Symbol("") -@test isempty(div("...").attributes) - -@test div[".class"]("...").name === :div -@test div[".class"]("...").text == "" -@test length(div[".class"]("...").nodes) === 1 -@test div[".class"]("...").nodes[1].text == "..." -@test div[".class"]("...").nodes[1].name === Symbol("") -@test length(div[".class"]("...").attributes) === 1 -@test div[".class"]("...").attributes[1] == (:class => "class") -@test div[:attribute].attributes[1] == (:attribute => "") -@test div[:attribute => "value"].attributes[1] == (:attribute => "value") - -let d = div(ul(map(li, [string(n) for n = 1:10]))) - @test d.name === :div - @test d.text == "" - @test isempty(d.attributes) - @test length(d.nodes) === 1 - let u = d.nodes[1] - @test u.name === :ul - @test u.text == "" - @test isempty(u.attributes) - @test length(u.nodes) === 10 - for n = 1:10 - let v = u.nodes[n] - @test v.name === :li - @test v.text == "" - @test isempty(v.attributes) - @test length(v.nodes) === 1 - @test v.nodes[1].name === Symbol("") - @test v.nodes[1].text == string(n) - @test !isdefined(v.nodes[1], :attributes) - @test !isdefined(v.nodes[1], :nodes) + @test div().name === :div + @test div().text == "" + @test isempty(div().nodes) + @test isempty(div().attributes) + + @test div("...").name === :div + @test div("...").text == "" + @test length(div("...").nodes) === 1 + @test div("...").nodes[1].text == "..." + @test div("...").nodes[1].name === Symbol("") + @test isempty(div("...").attributes) + + @test div[".class"]("...").name === :div + @test div[".class"]("...").text == "" + @test length(div[".class"]("...").nodes) === 1 + @test div[".class"]("...").nodes[1].text == "..." + @test div[".class"]("...").nodes[1].name === Symbol("") + @test length(div[".class"]("...").attributes) === 1 + @test div[".class"]("...").attributes[1] == (:class => "class") + @test div[:attribute].attributes[1] == (:attribute => "") + @test div[:attribute => "value"].attributes[1] == (:attribute => "value") + + let d = div(ul(map(li, [string(n) for n = 1:10]))) + @test d.name === :div + @test d.text == "" + @test isempty(d.attributes) + @test length(d.nodes) === 1 + let u = d.nodes[1] + @test u.name === :ul + @test u.text == "" + @test isempty(u.attributes) + @test length(u.nodes) === 10 + for n = 1:10 + let v = u.nodes[n] + @test v.name === :li + @test v.text == "" + @test isempty(v.attributes) + @test length(v.nodes) === 1 + @test v.nodes[1].name === Symbol("") + @test v.nodes[1].text == string(n) + @test !isdefined(v.nodes[1], :attributes) + @test !isdefined(v.nodes[1], :nodes) + end end end end -end -@tags script style img - -@test string(div(p("one"), p("two"))) == "

one

two

" -@test string(div[:key => "value"]) == "
" -@test string(p(" < > & ' \" ")) == "

< > & ' "

" -@test string(img[:src => "source"]) == "" -@test string(img[:none]) == "" -@test string(script(" < > & ' \" ")) == "" -@test string(style(" < > & ' \" ")) == "" -@test string(script) == "" + @test string(style(" < > & ' \" ")) == "" + @test string(script) == "" + @test string(style(" < > & ' \" ")) == "" + @test string(script) == "" - @test string(style(" < > & ' \" ")) == "" - @test string(script) == "