[ANN] Publish.jl

Hi all,

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.
  • Fully compliant commonmark parsing (plus useful extensions).
  • Cross-references across packages (awaiting a suitable syntax before finishing implementing).
  • General enough to be used not just for “package documentation”, but any kind of writing.
  • Full style and template customisation exposed to the user.
  • PDF output without having to manage any kind of LaTex environment.
  • Integrated project watching with LiveServer.jl.
  • And anything else we want, we’re greedy

How far along is it?

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.

42 Likes

Very cool! I’m excited to try this out.

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:

Is that an intentional design choice or maybe just a <meta viewport bug? Should I submit an issue?

1 Like

I just wanted to ask the same :wink:

Otherwise, really nice, I like the user-oriented approach and the reactive way of working on the docs, very cool!

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 :smiley: 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.

4 Likes

Will it provide a theme that looks like Documenter.jl? Kinda like Documenter’s layout & it has been widely used. Also, does it provide a dark theme?

All those are on the roadmap. I’ll get to them at some point.

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

docs/Project.toml
docs/toc.md
docs/src/<contents>
docs/assets

which looks more organized to me.

1 Like

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:

[publish]
toc = "docs/toc.md"

[publish.html]
css = ["docs/assets/custom.css"]

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.

1 Like

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.

1 Like

This is exactly what I’ve been looking for for months now, so thank you for building it!

1 Like

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.

4 Likes

I’ve used Publish.jl to host my first package documentation and it was a breeze!
https://lorenzoh.github.io/DataLoaders.jl/dev

1 Like

Should it be “Built” instead of “Build” in the footer?

1 Like

:rofl: yeah that should be “built”, thanks.

2 Likes

The newly tagged 0.3 adds evaluation of code blocks as well as a few minor bug fixes and typos.

1 Like

The badge in the README still links to 0.1.0. Is there a way to get a “latest release”-link and use that one?

1 Like

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.

See the note on “TagBot & tagged versions” here: https://juliadocs.github.io/Documenter.jl/stable/man/hosting/#GitHub-Actions.

2 Likes