Order and selection of built docs in Makedocs

[kescobo]

Related to #1013 (since the order of code execution in the project is critical, otherwise I'm referencing files before they're created), and maybe to #936 ?

make.jl:

using Documenter

makedocs(
    sitename="Fakedocs",
    pages=[
    "Test" => [
        "Foo" => "foo.md",
        "Bar" => "bar.md",
        ],
    ],
 )

src/foo.md:

```@repl
@info "Foo"
isfile("test.txt")
```

src/bar.md:

```@repl
@warn "Bar"
touch("test.txt")
```

I would expect the answer to isfile("test.txt") should be false, since "Foo"=> "foo.md" is listed first in pages, but I get true.

In addition, if I add

src/baz.md:

```@repl
touch("baz.md")
```

the file is created even though it's not listed in pages.

[mortenpi]

Hmm, this is a bit tricky. I am not actually sure how we decide the order of execution, but I think it's rather arbitrary. I am not sure that following the ordering pages in pages is the best general solution though, as you might want to execute pages that are down in the navigation menu before the ones that are on top.

How about the ability to declare a set of pages that get priority? That is, pass a vector to makedocs that says which files should be executed before all others, in the order the user passes them?

[kescobo]

I am not sure that following the ordering pages in pages is the best general solution though, as you might want to execute pages that are down in the navigation menu before the ones that are on top.

Good point, though I think the ordering in pages is a sensible default? The order does seem arbitrary - at one point I thought it was alphabetical, but my pages are 01...md, 02...md etc and they're still executed out of order.

[mortenpi]

As we also parse and execute pages that are not in pages, defaulting to filenames in alphabetical order might be better?

[kescobo]

Huh, I didn't know that. I'm guessing that's why other markdown files in src/ are executed even if it's not in pages? That was unexpected for me.

I guess I don't know the use case for stuff that's not in pages - are there examples you're aware of? I guess I don't have really strong opinions on defaults so long as there is a way to pick and chose.

[mortenpi]

Yep, we are executing everything if I remember correctly.

I guess I don't know the use case for stuff that's not in pages - are there examples you're aware of?

You omit pages when building with format = Markdown(), since the page hierarchy is then defined in mkdocs.yml, so that's where that behaviour comes from. pages basically just defines the sidebar in the HTML output.

We could, of course, collect all .md files only when pages is not provided and build only the files in pages if it is. But it does allow building pages that are omitted from the sidebar (even though it is a bit of an edge case and duplicates hide()).

[kescobo]

We could, of course, collect all .md files only when pages is not provided and build only the files in pages if it is.

This would make a lot of sense to me.

[mortenpi]

We could, of course, collect all .md files only when pages is not provided and build only the files in pages if it is.

This would make a lot of sense to me.

I did run into a use case where I would actually like to properly build the non-pages pages -- for hidden draft pages (hence #1031). But not sure if it makes sense to have that as a (default) feature of Documenter.