Document makedocs argument pages for LaTeX output

[ChromatinRemodeling]

Trying to fix #2132.

[mortenpi]

Actually, I'm leaning towards considering this a bug. IIRC, for HTML we do populate pages automatically, and I'm actually unsure why it's not also happening with LaTeX. From the makedocs docstrings:

If omitted, Documenter will automatically generate a flat list of pages based on the files present in the source directory.

I would be okay merging this doc note if we make it clear that it's a bug. But it would be good to also check why the documented behavior is not working -- it might be a simple fix.

[ChromatinRemodeling]

In my case, changing the following lines from

Documenter.jl/src/latex/LaTeXWriter.jl

Lines 115 to 116 in 233a782

	writeheader(context, doc, settings)
	for (title, filename, depth) in files(doc.user.pages)

to

if isempty(doc.user.pages)
    @warn "No pages found. Using doc.internal.navlist for retrieving pages."
    contextpages = [i.page for i in doc.internal.navlist]
else
    contextpages = doc.user.pages
end
writeheader(context, doc, settings)
for (title, filename, depth) in files(contextpages)

seems to fix the problem. But I'm not sure how to properly test the code, neither do I know if it is safe to use doc.internal.navlist. Should I update the pull request to include this change?

[ChromatinRemodeling]

Update: I am able to build the whole Documenter.jl documents with the tweak above, by:

• commenting out the pages in docs/make.jl and the if "pdf" in ARGS deployment part
• passing remotes = nothing and format = Documenter.LaTeX(platform = "none") into makedocs
• manually fixing some broken references in the .md files
• running julia --project docs/make.jl pdf
• manually fixing some \includegraphics bugs in the .tex file (Wrong \includegraphics image path at creating LaTeX output #2434 )
• run latexmk -f -interaction=batchmode -halt-on-error -view=none -lualatex -shell-escape Documenter.jl.tex

Hope this is helpful.

[mortenpi]

Could you try adding another test build that looks like this, but doesn't specify pages?

Documenter.jl/test/examples/make.jl

Lines 829 to 847 in d521d5a

	examples_latex_showcase_texonly_doc = if "latex_showcase_texonly" in EXAMPLE_BUILDS
	@info("Building mock package docs: LaTeXWriter/latex_showcase_texonly")
	@quietly makedocs(
	format = Documenter.LaTeX(platform = "none", version = v"1.2.3"),
	sitename = "Documenter LaTeX Showcase",
	root = examples_root,
	build = "builds/latex_showcase_texonly",
	source = "src.latex_showcase",
	pages = ["Showcase" => ["showcase.md", "docstrings.md"]],
	remotes = Dict(@__DIR__() => (TestRemote(), "6ef16754bc5da93f67a4323fb204c5bd3e64f336")),
	doctest = false,
	debug = true,
	warnonly = [:docs_block, :cross_references],
	)
	else
	@info "Skipping build: LaTeXWriter/latex_showcase_texonly"
	@debug "Controlling variables:" EXAMPLE_BUILDS get(ENV, "DOCUMENTER_TEST_EXAMPLES", nothing)
	nothing
	end

It should ideally pick up the pages from https://github.com/JuliaDocs/Documenter.jl/tree/master/test/examples/src.latex_showcase

It would also need a corresponding test here, and maybe we can even reuse the references/latex_showcase.tex reference file:

Documenter.jl/test/examples/tests.jl

Lines 340 to 349 in d521d5a

	@testset "PDF/LaTeX: showcase (TeX only)" begin
	doc = Main.examples_latex_showcase_texonly_doc
	@test isa(doc, Documenter.Documenter.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

[mortenpi]

Hmm. In HTMLWriter we use doc.blueprint.pages:

Documenter.jl/src/html/HTMLWriter.jl

Lines 695 to 699 in d521d5a

	if isempty(doc.blueprint.pages)
	error("Aborting HTML build: no pages under src/")
	elseif !haskey(doc.blueprint.pages, "index.md")
	@warn "Can't generate landing page (index.html): src/index.md missing" keys(doc.blueprint.pages)
	end

Maybe if we use that instead of doc.user.pages, then we don't need to use .navlist?

[mortenpi]

Let's merge this as is, since it can be useful for users. We can fix the behavior in a follow-up PR.