Deployment: deploy document AND fail CI

[asinghvi17]

So currently it's a bit difficult to do this, since users don't have access to doc unless debug=true in makedocs. But here's what I did to make this happen:

doc = makedocs(; debug = true, ...)
deploydocs(...)

# Return with a nonzero exit code if there were any errors
error_set = doc.internal.errors
exit_code = issubset(error_set, (:missing_docs, :cross_references)) ? 0 : 1
exit(exit_code)

I guess this would require a breaking release, but in a hypothetical Documenter v2.0 it would make things much nicer if we could pass doc around - makedocs would return doc and then deploydocs(doc; kwargs...) to avoid a lot of hassle.

[mortenpi]

I don't think this would necessarily have to be breaking. We can have an option to return doc (not sure if we use debug for anything other than returning doc), and passing doc positionally to deploydocs should also be non-breaking.

But I actually kinda want to merge makedocs and deploydocs to avoid the separation between them altogether, and have you control whether it deploys or not with some argument. The related thing is #1350, where you'd control things via command line arguments then.

But that might be a bit contrary to what you want -- you actually want to introspect doc in make.jl if I understand correctly?

[asinghvi17]

So I want three things primarily:

• introspect, modify, etc. doc in make.jl
• deploy doc to multiple targets with separate calls to deploydocs
• construct a document without rendering it, and then render it where you choose

As long as deploydocs still exists and is something that's just called by make.jl there's no issue. But it is nice for the user to be able to call deploydocs(doc; deploy_only_kwargs...) to get rid of having to propagate random things around. And control over rendering is also nice to have.

[mortenpi]

• construct a document without rendering it, and then render it where you choose

A very hacky option could be add an option to return doc without calling the writer? And then have a makedocs mode or a a separate function (probably better) that takes doc and renders it?

[asinghvi17]

Well you can just not pass format in, but the question is how do you render the doc after that. I happen to know how because I wrote that function in DV but we should have some better solution. Maybe some invocation of the selectors api directly that we bless?

[mortenpi]

Technically, you can probably just call render, no? It does pick the renderer from the doc object.

Documenter.jl/src/writers.jl

Lines 41 to 48 in 25f9027

	function render(doc::Documenter.Document)
	# Render each format. Additional formats must define an `order`, `matcher`, `runner`, as
	# well as their own rendering methods in a separate module.
	for each in doc.user.format
	Selectors.dispatch(FormatSelector, each, doc)
	end
	return
	end

It's what gets called in the last build step:

Documenter.jl/src/builder_pipeline.jl

Line 266 in 25f9027

Documenter.render(doc)

[asinghvi17]

You could but you have to mutate the doc then. Or are you saying some kwarg will just halt rendering entirely?

[mortenpi]

Or are you saying some kwarg will just halt rendering entirely?

You mean to get the doc out before rendering? Yea, that's what I imagine. It's not pretty, but it would be pretty simple to do.

[asinghvi17]

Specifically that the format selector stage would not be invoked...returning the doc would be a different keyword from that?

Or makedocs could just return the doc by default, that's not breaking