Allow build order of pages to be specified

CHANGELOG.md

@@ -4,6 +4,10 @@
 
 * Documenter v0.23 requires Julia v1.0. ([#1015][github-1015])
 
+* ![Feature][badge-feature] `makedocs` now accepts the `expandfirst` argument, which allows specifying a set of pages that should be evaluated before the other. ([#1027][github-1027], [#1029][github-1029])
+
+* ![Enhancement][badge-enhancement] The evaluation order of pages is now fixed (unless customized with `expandfirst`). The pages are evaluated in the alphabetical order of their file paths. ([#1027][github-1027], [#1029][github-1029])
+
 * ![Enhancement][badge-enhancement] The logo image in the HTML output will now always point to the first page in the navigation menu (as opposed to `index.html`, which may or may not exist). When using pretty URLs, the `index.html` part now omitted from the logo link URL. ([#1005][github-1005])
 
 * ![Enhancement][badge-enhancement] Minor changes to how doctesting errors are printed. ([#1028][github-1028])
@@ -325,7 +329,9 @@
 [github-1009]: https://github.com/JuliaDocs/Documenter.jl/pull/1009
 [github-1014]: https://github.com/JuliaDocs/Documenter.jl/pull/1014
 [github-1015]: https://github.com/JuliaDocs/Documenter.jl/pull/1015
+[github-1027]: https://github.com/JuliaDocs/Documenter.jl/issues/1027
 [github-1028]: https://github.com/JuliaDocs/Documenter.jl/pull/1028
+[github-1029]: https://github.com/JuliaDocs/Documenter.jl/pull/1029
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

src/Documenter.jl

@@ -65,6 +65,7 @@ export Deps, makedocs, deploydocs, hide
         repo    = "",
         highlightsig = true,
         sitename = "",
+        expandfirst = [],
     )
 
 Combines markdown files and inline docstrings into an interlinked document.
@@ -159,6 +160,16 @@ is enabled by default.
 
 **`sitename`** is displayed in the title bar and/or the navigation menu when applicable.
 
+**`expandfirst`** allows some of the pages to be _expanded_ (i.e. at-blocks evaluated etc.)
+before the others. Documenter normally evaluates the files in the alphabetic order of their
+file paths relative to `src`, but `expandfirst` allows some pages to be prioritized.
+
+For example, if you have `foo.md` and `bar.md`, `bar.md` would normally be evaluated before
+`foo.md`. But with `expandfirst = ["foo.md"]`, you can force `foo.md` to be evaluated first.
+
+Evaluation order among the `expandfirst` pages is according to the order they appear in the
+argument.
+
 # Experimental keywords
 
 In addition to standard arguments there is a set of non-finalized experimental keyword

src/Documents.jl

@@ -197,6 +197,7 @@ struct User
     strict::Bool              # Throw an exception when any warnings are encountered.
     modules :: Set{Module}    # Which modules to check for missing docs?
     pages   :: Vector{Any}    # Ordering of document pages specified by the user.
+    expandfirst::Vector{String} # List of pages that get "expanded" before others
     repo    :: String  # Template for URL to source code repo
     sitename:: String
     authors :: String
@@ -249,6 +250,7 @@ function Document(plugins = nothing;
         strict::Bool                 = false,
         modules  :: Utilities.ModVec = Module[],
         pages    :: Vector           = Any[],
+        expandfirst :: Vector        = String[],
         repo     :: AbstractString   = "",
         sitename :: AbstractString   = "",
         authors  :: AbstractString   = "",
@@ -280,6 +282,7 @@ function Document(plugins = nothing;
         strict,
         Utilities.submodules(modules),
         pages,
+        expandfirst,
         repo,
         sitename,
         authors,

src/Expanders.jl

@@ -24,7 +24,20 @@ import Base64: stringmime
 
 
 function expand(doc::Documents.Document)
-    for (src, page) in doc.internal.pages
+    priority_pages = filter(doc.user.expandfirst) do src
+        if src in keys(doc.internal.pages)
+            return true
+        else
+            @warn "$(src) in expandfirst does not exist"
+            return false
+        end
+    end
+    normal_pages = filter(src -> !(src in priority_pages), keys(doc.internal.pages))
+    normal_pages = sort([src for src in normal_pages])
+    @debug "pages" keys(doc.internal.pages) priority_pages normal_pages
+    for src in Iterators.flatten([priority_pages, normal_pages])
+        page = doc.internal.pages[src]
+        @debug "Running ExpanderPipeline on $src"
         empty!(page.globals.meta)
         for element in page.elements
             Selectors.dispatch(ExpanderPipeline, element, page, doc)

test/examples/make.jl

@@ -103,13 +103,16 @@ const examples_root = @__DIR__
 const builds_directory = joinpath(examples_root, "builds")
 ispath(builds_directory) && rm(builds_directory, recursive=true)
 
+expandfirst = ["expandorder/AA.md"]
+
 @info("Building mock package docs: MarkdownWriter")
 examples_markdown_doc = makedocs(
     format = Markdown(),
     debug = true,
     root  = examples_root,
     build = "builds/markdown",
     doctest = false,
+    expandfirst = expandfirst,
 )
 
 
@@ -127,7 +130,12 @@ htmlbuild_pages = Any[
         "Page X" => "hidden/x.md",
         "hidden/y.md",
         "hidden/z.md",
-    ])
+    ]),
+    "Expandorder" => [
+        "expandorder/00.md",
+        "expandorder/01.md",
+        "expandorder/AA.md",
+    ]
 ]
 
 @info("Building mock package docs: HTMLWriter / local build")
@@ -138,6 +146,7 @@ examples_html_local_doc = makedocs(
     doctestfilters = [r"Ptr{0x[0-9]+}"],
     sitename = "Documenter example",
     pages = htmlbuild_pages,
+    expandfirst = expandfirst,
 
     linkcheck = true,
     linkcheck_ignore = [r"(x|y).md", "z.md", r":func:.*"],
@@ -180,6 +189,7 @@ examples_html_deploy_doc = withassets("images/logo.png", "images/logo.jpg", "ima
         doctestfilters = [r"Ptr{0x[0-9]+}"],
         sitename = "Documenter example",
         pages = htmlbuild_pages,
+        expandfirst = expandfirst,
         doctest = false,
         Documenter.HTML(
             assets = [

test/examples/src/expandorder/00.md

@@ -0,0 +1,7 @@
+# Expand order test 00
+
+Filename suggest that this will be expanded before `01.md`.
+
+```@example
+touch("00.txt")
+```

test/examples/src/expandorder/01.md

@@ -0,0 +1,11 @@
+# Expand order test 01
+
+This should be expanded after `00.md` and `AA.md`.
+
+```@example
+isfile("00.txt") || error("00.txt missing")
+```
+
+```@example
+isfile("AA.txt") || error("AA.txt missing")
+```

test/examples/src/expandorder/AA.md

@@ -0,0 +1,8 @@
+# Expand order test AA
+
+Filename suggest that this will be expanded after `00.md` and `01.md`.
+Hence we use `expandfirst` to force this to be expanded first.
+
+```@example
+touch("AA.txt")
+```

test/examples/tests.jl

@@ -50,7 +50,7 @@ end
 
         @test realpath(doc.internal.assets) == realpath(joinpath(dirname(@__FILE__), "..", "..", "assets"))
 
-        @test length(doc.internal.pages) == 10
+        @test length(doc.internal.pages) == 13
 
         let headers = doc.internal.headers
             @test Documenter.Anchors.exists(headers, "Documentation")