I’m pleased to announce the (very early) 0.1 release of Publish.jl. An experimental package in the same ecosystem “space” as Documenter.jl. It’s purpose is to explore alternative design decisions (potentially major and breaking ones) to those that we’ve taken over the years with Documenter, with the hopes to eventually upstream/integrate them in some way with the rest of the ecosystem.
What Publish.jl aims to provide?
Declarative configurations rather than build scripts.
I’ve used it build it’s own package documentation in it’s entirety, so in that sense it’s already usable. Styling is still bare-bones with the built in templates, but those are easily replaceable by users and future improvements for the defaults are planned.
How to try it?
pkg> add Publish
julia> using Publish
julia> serve(Publish) # start server to serve Publish's docs.
The package docs go into much more depth on what’s available at the moment.
It’s broken?
Please open an issue, it’s very likely there’ll be stuff that’s boken/not implemented currently.
Is the layout supposed to be mobile-style on all displays? I checked out the sample docs on my desktop, and the layout looks like it thinks I’m using a phone or other small screen with all of the navigation contents hidden behind a hamburger menu:
It’s intensional at the moment, in the sense that I’ve just not written the CSS yet to adjust the layout based on screen size it’s on the to-do list though.
Yeah, it’s nice being able to get instant feedback. You can get the same effect with Documenter by importing LiveServer.jl yourself, though it feels like it should be a built in feature so that users will use that workflow by default.
It’s not mentioned early in the docs, but this also works with live reloading docstrings with Revise if you happen to have that loaded as well.
I like the idea to use Project.toml and toc.md for the configuration. Just wondering if it’s better to have the Documenter folder structure, that lets all doc related files live inside docs folder and allow some documentation specific dependencies and configurations in docs/Project.toml, so that what’s inside docs becomes
Right, the default structure that Publish accepts isn’t going to be suitable for all projects, hence why you can adjust the paths in your Project.toml such as:
To point your table-of-contents and custom CSS (or anything else you’re using) at files in your docs/ directory. That’s one option and allows referencing content in your src/ directory if you’re wanting to use the package source code for some literate programming.
The other option is to use a separate docs/Project.toml, which is fine. It’ll just not allow you to directly reference any files outside of the docs/ directory tree. When you use serve or deploy to generate output, just point them at the configuration rather than the Module object, i.e.
julia> serve("docs/Project.toml")
This will currently not pick up docstring references from the package, which is an oversight on my part, but shouldn’t be too hard to fix for the next release so that you can specify which modules to check within your configuration.
One situation, where putting the Project.toml under a docs/ folder might be useful would be for doctest-specific dependencies. It doesn’t look like doctests are currently supported, but might be added eventually? Perhaps that could also be it’s own entry under [publish], but in that case it probably wouldn’t be possible to just activate the project for debugging.
Yes, if you’re needing doctest only deps then a separate docs/Project.toml is the correct way to use Publish. Some form of doctesting will definitely be added at some point.
0.2 is now out. Theming is better exposed to users, so most of the stylistic elements of the output can be switched out for completely custom looking results.
Additionally the package has had some internal refactoring to use FileTrees.jl for the internal representation, which allows for lazy evaluation of files and parallel writing of output. Parallel writing doesn’t appear to have much benefit on small projects and so it isn’t enabled by default, but may help on very large ones.
There’s meant to be an action that creates the stable docs and triggers when tags get pushed to the repo, but it appears that if another action (TagBot) is what pushes the tag then the second action doesn’t happen. https://github.community/t/github-actions-workflow-not-triggering-with-tag-push/17053 suggests that a personal access token is what’s needed.
it’s on the to-do list though.
yeah that should be “built”, thanks.