Documenter.jl icon indicating copy to clipboard operation
Documenter.jl copied to clipboard

Is `docs/instantiate.jl` obsolete?

Open goerz opened this issue 1 year ago • 1 comments

The docs/instantiate.jl file here feels like it's maybe obsolete or at least outdated

https://github.com/JuliaDocs/Documenter.jl/blob/a6cdf2038d869ef8cb8d0cb697c82dbb6c4e987e/docs/instantiate.jl#L1-L22

I'm quite confused as to what this is trying to do with respect to DocumenterTools. It seems to me like DocumenterTools should just be a dependency of Documenter, and act as a re-exported submodule, since we're documenting the usage of DocumenterTools fully inside the Documenter documentation.

As for the "activate the docs environment", maybe https://github.com/JuliaDocs/Documenter.jl/issues/1413#issuecomment-1942392352 would be a better approach, and we can just delete docs/instantiate.jl?

goerz avatar Feb 13 '24 21:02 goerz

DocumenterTools has dependencies we don't want in Documenter, hence why it needs to be a separate package. But it accesses Documenter's internals a bit, so it needs Documenter as a dependency.

That said.. I think, right now, we could probably just have DocumenterTools be a normal dependency of docs/Project.toml. These instantiation hoops were necessary when Documenter was making a breaking release.

Including it within the Documenter manual was just a choice we made at some point, mostly to make it more easily discoverable. But I think a MultiDocumenter-approach would be better (i.e. DocumenterTools would build its own manual).

mortenpi avatar Feb 13 '24 21:02 mortenpi