Some speculation about the future of Documenter's user-facing API.

documenter-api-updates.jl

# This would be make.jl.
#
# The user can then interact with this configuration through the
# command line:
#
# julia docs/make.jl doctest
# julia docs/make.jl build --html
# julia docs/make.jl deploy --latex --html

using Documenter, DocumenterLaTeX

docs = Document(
    modules = [Documenter],
    sitename = "Documenter.jl", # sitename is not necessarily a good name for this...
    authors = "Michael Hatherly, Morten Piibeleht, and contributors.",
    pages = [ ... ],
)

htmlwriter = Writers.HTML(
    assets = ["assets/favicon.ico"],
    pretty_urls = true,
    canonical_url = "https://juliadocs.github.io/Documenter.jl/stable/",
)

pdfwriter = DocumenterLaTeX.LaTeX(
    output_filename = "documenter.pdf",
)

deploy = DeployGitHub(
    repo = "github.com/JuliaDocs/Documenter.jl.git",
    branch = "gh-pages",
)

Documenter.run(ARGS, docs, htmlwriter, pdfwriter, deploy)


# All the objects created here (docs, *writer, deploy) would be descriptive only.
# It's up to run() to actually build something coherent out of them.
#
# Under the hood, run() would look something like this (extremely sketchy):

blueprint = parse(docs)
if "--doctest" doctest(blueprint) end
document = build(blueprint)
rendered_html = render(htmlwriter, deploy, document; output_dir=tmpdir())
rendered_pdf  = render(pdfwriter, deploy, document; output_dir=rendered_html.output_dir)
install(rendered_html, deploy)

# The reason render() needs both the writer and deploy is because deployment details can
# affect how a page is rendered (e.g. repo URL).
#
# If the user wants more control over the build steps, then they can also write custom
# run()-like steps in make.jl, instead of using run().

# Finally, this is a bit speculative, but we could also provide a
# mechanism to read in the configuration:
#
#     Documenter.loadconfig(Pkg.dir("Documenter", "docs/make.jl"))
#
# This would eval() the contents of `make.jl` (probably in a submodule),
# overriding Documenter.run() in a way that nothing gets run and returns an object
# that the 
#
# This way the user can e.g. run doctests during testing. In `runtests.jl`:

using Documenter
docscfg = Documenter.loadconfig(Pkg.dir("Documenter", "docs/make.jl"))
@test Documenter.doctest(docscfg)

# Would basically be equivalent to `julia docs/make.jl --doctest`