ANN: Documenter 0.20 with breaking changes released

[mortenpi]

I am happy to announce that Documenter 0.20 has now been tagged in METADATA! For a full list of changes and for instructions on upgrading, please see the v0.20.0 CHANGELOG.

It makes breaking changes to makedocs and deploydocs, so existing make.jl scripts need to be updated before they work with this version. The changes were mainly to make Documenter’s default behavior saner. If you are not restricting Documenter’s version, your Travis deployments will likely fail now, silently.

Together with the new release, we also tagged 3 new related packages:

• The Markdown/MkDocs and PDF/LaTeX backends have been (kind of) moved to separate packages:
  DocumenterMarkdown and DocumenterLaTeX, respectively. They function as plugins to Documenter, so you only need to do e.g. using DocumenterMarkdown to re-enable the Markdown/MkDocs backend.

• Various utilities that are not used in the actual build process (i.e. not needed in Travis deployments) and only used by developers locally (such as the helper functions for SSH key generation) now live in DocumenterTools. The main motivation here is that this allows us to be more liberal with dependencies for the developer tools.

From this version on, we will reserve the right to make breaking changes in accordance with semver, meaning that future 0.x minor releases may break deployments if Documenter’s version is not capped or fixed. We recommend that you do cap it — see the section on Travis in the documentation for more information on how to achieve this. You may also find these earlier PSAs interesting:

PSA: Documenter.jl breaking changes & version capping

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. Howev…

PSA: Use a project for building your docs

This is a simple guide on how to best build your documentation in Julia v1.0 if you are using Documenter. The old way If you are using Documenter you probably have something like the following in your .travis.yml file for building your documentation: after_success: - julia -e 'Pkg.add("Documenter")' - julia -e 'cd(Pkg.dir("PACKAGE_NAME")); include(joinpath("docs", "make.jl"))' Why is this bad? Here are some reasons: There is no good way to add doc-build dependencies, you have to add th…

The next steps are to do some final cleanup of the API and then go for 1.0, hopefully in the not too distant future. With 1.x releases, we will go back to promising that minor releases will not break existing setups, but that you would still have access to automatic non-breaking updates.

Finally, I would like to thank @fredrikekre for all his work on this release, and also all the other people who have kindly volunteered their time to contribute!