Clarify how to use artifact-based themes in documentation

[darsnack]

Currently, it seems like the only way to use PublishThemes is to override the following before building the docs:

Publish.Themes.default() = artifact"my-theme"

This also applies to any theme installed via the artifacts system.

[darsnack]

The comment about only applies to < v0.9. The latest version breaks the hack above.

It should correctly be classified as a hack. The proper process for using a custom theme not stored with the repo but as an artifact should be:

• have a deployment script that copies the artifact locally under _my_theme and configure Project.toml accordingly
• use a 0-arity function in Project.toml that returns artifact"my_theme"

Assuming this is the correct process, I'm changing this issue to just add this clarification to the docs.

[MichaelHatherly]

Does what's described in https://michaelhatherly.github.io/Publish.jl/dev/docs/themes.html#custom-themes work, i.e. just providing a path to the directory with your custom theme files?

[darsnack]

Yes that works, but if the theme files are not stored as part of the repository but in the Artifacts.toml, then you need copy the artifact to whatever local path is specified under toml["publish"]["theme"]. Writing theme = artifact"my-theme" directly in the Project.toml won't work. You could also write out the absolute path to the artifact in the Project.toml too, I suppose.

[MichaelHatherly]

Ah, makes sense. Yes, docs can be improved to cover that I think.

[MichaelHatherly]

(Or add some kind of feature that checks for the existence of an artifact with the right name and loads that.)

[darsnack]

Yeah, perhaps resolving a string should first check for a folder at the given path then check for an artifact with the given name?

[MichaelHatherly]

That could be a reasonable route to try. Jumping through the hoops of copying an artifact first is a bit annoying.