diff --git a/CHANGELOG.md b/CHANGELOG.md index a026826403..f064e782c0 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,9 @@ # Documenter.jl changelog +## Version `v0.25.1` + +* ![Enhancement][badge-enhancement] When automatically determining the page list (i.e. `pages` is not passed to `makedocs`), Documenter now lists `index.md` before other pages. ([#1355][github-1355]) + ## Version `v0.25.0` * ![Enhancement][badge-enhancement] When deploying with `deploydocs`, any SSH username can now be used (not just `git`), by prepending `username@` to the repository URL in the `repo` argument. ([#1285][github-1285]) @@ -588,6 +592,7 @@ [github-1339]: https://github.com/JuliaDocs/Documenter.jl/pull/1339 [github-1344]: https://github.com/JuliaDocs/Documenter.jl/issues/1344 [github-1345]: https://github.com/JuliaDocs/Documenter.jl/pull/1345 +[github-1355]: https://github.com/JuliaDocs/Documenter.jl/pull/1355 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl diff --git a/src/Builder.jl b/src/Builder.jl index 6c83e5204b..dced7743c8 100644 --- a/src/Builder.jl +++ b/src/Builder.jl @@ -138,7 +138,7 @@ function Selectors.runner(::Type{SetupBuildDirectory}, doc::Documents.Document) # If the user hasn't specified the page list, then we'll just default to a # flat list of all the markdown files we found, sorted by the filesystem # path (it will group them by subdirectory, among others). - userpages = isempty(doc.user.pages) ? sort(mdpages) : doc.user.pages + userpages = isempty(doc.user.pages) ? sort(mdpages, lt=lt_page) : doc.user.pages # Populating the .navtree and .navlist. # We need the for loop because we can't assign to the fields of the immutable @@ -159,6 +159,19 @@ function Selectors.runner(::Type{SetupBuildDirectory}, doc::Documents.Document) end end +""" + lt_page(a::AbstractString, b::AbstractString) + +Checks if the page path `a` should come before `b` in a sorted list. Falls back to standard +string sorting, except for prioritizing `index.md` (i.e. `index.md` always comes first). +""" +function lt_page(a, b) + # note: length("index.md") == 8 + a = endswith(a, "index.md") ? chop(a; tail = 8) : a + b = endswith(b, "index.md") ? chop(b; tail = 8) : b + return a < b +end + """ $(SIGNATURES) diff --git a/test/expanders.jl b/test/expanders.jl deleted file mode 100644 index d572de8981..0000000000 --- a/test/expanders.jl +++ /dev/null @@ -1,30 +0,0 @@ -# Docstring signature syntax highlighting tests. -module HighlightSig - using Test - import Markdown - import Documenter.Expanders: highlightsig! - - @testset "highlightsig!" begin - s = """ - foo(bar::Baz) - --- - foo(bar::Baz) - """ - original = Markdown.parse(s) - md = Markdown.parse(s) - highlightsig!(md) - @test isempty(original.content[1].language) - @test md.content[1].language == "julia" - @test original.content[end].language == md.content[end].language - - s = """ - ```lang - foo(bar::Baz) - ``` - """ - original = Markdown.parse(s) - md = Markdown.parse(s) - highlightsig!(md) - @test original == md - end -end diff --git a/test/pipeline.jl b/test/pipeline.jl new file mode 100644 index 0000000000..453089c506 --- /dev/null +++ b/test/pipeline.jl @@ -0,0 +1,76 @@ +module PipeLineTests +using Test + +@testset "Builder.lt_page" begin + using Documenter.Builder: lt_page + # Checks to make sure that only exactly one of ab is true for given a & b + iscorrectisless(a,b) = sum([lt_page(a, b), a == b, lt_page(b, a)]) == 1 + # Test equal strings: + for a in ["index.md", "foo/index.md", "foo.md", "bar/foo.md", "foo/bar/baz/qux", "", "α", "α/β", "α/index.md"] + @test !lt_page(a, a) + @test iscorrectisless(a, a) + end + # Test less thans + for (a, b) in [ + ("a", "b"), ("α", "β"), ("b", "α"), + # index.md takes precedence + ("index.md", "a"), + ("index.md", "index.mm"), + ("index.md", "foo.md"), + ("index.md", "bar/foo.md"), + # Also in subdirectories: + ("foo/index.md", "foo/a"), + ("foo/index.md", "foo/index.mm"), + ("foo/index.md", "foo/foo.md"), + ("foo/index.md", "foo/bar/foo.md"), + # But not over stuff that is outside of the subdirectory + ("a", "foo/index.md"), + ("α", "α/index.md"), + ("foo/index.md", "g"), + ("bar/index.md", "foo/index.md"), + ("bar/qux/index.md", "foo/index.md"), + ] + @test lt_page(a, b) + @test iscorrectisless(a, b) + end + + @test sort(["foo", "bar"], lt=lt_page) == ["bar", "foo"] + @test sort(["foo", "foo/bar"], lt=lt_page) == ["foo", "foo/bar"] + @test sort(["foo", "f/bar"], lt=lt_page) == ["f/bar", "foo"] + @test sort(["foo", "index.md"], lt=lt_page) == ["index.md", "foo"] + @test sort(["foo.md", "foo/index.md", "index.md", "foo/foo.md"], lt=lt_page) == ["index.md", "foo.md", "foo/index.md", "foo/foo.md"] + @test sort(["foo.md", "ϕωω/index.md", "index.md", "foo/foo.md"], lt=lt_page) == ["index.md", "foo.md", "foo/foo.md", "ϕωω/index.md"] +end + +# Docstring signature syntax highlighting tests. +module HighlightSig + using Test + import Markdown + import Documenter.Expanders: highlightsig! + + @testset "highlightsig!" begin + s = """ + foo(bar::Baz) + --- + foo(bar::Baz) + """ + original = Markdown.parse(s) + md = Markdown.parse(s) + highlightsig!(md) + @test isempty(original.content[1].language) + @test md.content[1].language == "julia" + @test original.content[end].language == md.content[end].language + + s = """ + ```lang + foo(bar::Baz) + ``` + """ + original = Markdown.parse(s) + md = Markdown.parse(s) + highlightsig!(md) + @test original == md + end +end + +end diff --git a/test/runtests.jl b/test/runtests.jl index 773b596d5e..c7e5e968ec 100644 --- a/test/runtests.jl +++ b/test/runtests.jl @@ -50,8 +50,8 @@ include("TestUtilities.jl"); using .TestUtilities # MDFlatten tests. include("mdflatten.jl") - # Expanders - include("expanders.jl") + # Main build pipeline (Builder and Expanders modules) + include("pipeline.jl") # HTMLWriter include("htmlwriter.jl")