Declarative Documenter configuration

[c42f]

It would be great to be able to introspect and control the documentation generation process from code outside the package itself.

• It would allow auto-configuration of CI resources, decoupling CI more from the doc build script (Related - New API for deployment #1087)
• For JuliaHub, we may want to link package docs to each other (https://github.com/JuliaComputing/JuliaHub/issues/55) which would require the docs for the package to be built in the context of a larger system.

It would seem that a good way to do this is to have declarative configuration in a script, as mentioned by @davidanthoff in #1087 (comment)

I think that would also imply moving away from this model of having a make.jl script that does different things depending on the env it is run, but instead either have a more declarative config file or something like docs/docconfig.jl that only populates some data structures about the structure of the docs, but doesn't actually trigger anything like a build or deployment.

I feel the ecosystem is fairly well set up for this, as the Documentation configuration for simple package documentation builds is already largely declarative.

[tkf]

👍 It'd be great to move to more declarative API. Or maybe even just a function-based API JuliaDocs/DocumentationGenerator.jl#142 so that DocumentationGenerator.jl can be documentation framework-agnostic (e.g., maybe you'd want to use Franklin.jl instead).

[MichaelHatherly]

Would definitely be good to move in this direction. I've been going through some possible options in CommonMark.jl for declarative configuration of parsing and rendering that would hopefully just fit into the ecosystem; tying this all together, whether it be Franklin, PkgPages, Documenter, Literate, Weave, or any other option would be ideal (though maybe a little too hopeful). Do we want to just piggyback off of Project.toml files and add metadata there such as

[docs]
# some docs-specific config...

or have another config file for this? For anyone familiar with Pkg, are there any issues related to adding custom data to Project.toml that would come back to bite us?

[KristofferC]

For anyone familiar with Pkg, are there any issues related to adding custom data to Project.toml that would come back to bite us?

Not really, unless Pkg would want to use the exact same key but I don't think we would want to use [docs] for anything in Pkg, especially not if Documenter itself starts using it. Although, perhaps it makes sense to have its own file in the docs folder.

[davidanthoff]

Just another upvote for this. I've been thinking a bit about integrating docs properly into the VS Code extension (julia-vscode/julia-vscode#1550), but having something like this issue is kind of a prerequisite for that, I think.