PSA: Documenter.jl breaking changes & version capping

Tooling
, , ,
1

This is relevant for package developers using Documenter.jl for their package documentation.

The upcoming Documenter 0.20 will introduce breaking changes to the way makedocs and deploydocs arguments are interpreted. This means that most existing make.jl scripts have to be updated before they work correctly with the new version.

As you might have already noticed, a bunch of METADATA-registered packages just got hit with automated PRs that cap the Documenter version used in Travis to 0.19. However, it was only possible to do this automatically for about half the packages that use Documenter.

So for packages that did not get a PR (including all unregistered and private ones), you need to cap Documenter manually:

  • If you are using a docs/Project.toml file (see the previous PSA on Documenter and projects; this is the recommended setup), you should make sure that you have a [compat] section in there, capping Documenter to 0.19:

    [compat]
Documenter = "~0.19"

  • If you are installing Documenter in .travis.yml directly (on Julia 0.7/1.0), you should update the line with the Pkg.add to be something like:

    julia -e 'using Pkg; ps=PackageSpec(name="Documenter", version="0.19"); Pkg.add(ps); Pkg.pin(ps)'

  • :sauropod: If you are building docs on Julia <= 0.6, you do not need to worry, as Documenter 0.20 will be 0.7/1.0-only. But if upgrading the package is on the roadmap, you could change to Pkg.add("Documenter") in .travis.yml to Pkg.add("Documenter", v"0.19", v"0.20-") as a reminder.

In the future, we would like to reserve the right to make breaking changes to Documenter in accordance with semver. This means that you should either have Documenter fixed to a specific 0.x version or be ready to deal with potential sudden documentation build failures when new Documenter versions get released.

There will also be another announcement on Discourse when 0.20 gets tagged and merged. It will also include a guide for upgrading your make.jl file. But for those who are curious, you may take a look at the current CHANGELOG to get a glimpse of the upcoming changes.

18 Likes
2

I would like to thank the Documenter.jl maintainers for providing all this support for the API change in addition to making such a useful package. This kind of approach is exemplary for an open source package.

18 Likes
3

This was very well handled! Thank you.

4

Bumping this to the top just one more time. We intend to tag Documenter 0.20 over the weekend.

If you haven’t capped Documenter’s version yet, be warned that your automatic documentation deployments will most likely start breaking silently next week. As far as I can tell, many of the repositories that did not get an automated PR will be affected.

At this point, the best option is probably to update make.jl as soon as 0.20 gets released and cap Documenter to that version. It involves only a few small changes to the makedocs and deploydocs arguments.

1 Like