ANN: Documenter 0.24

Package Announcements
, ,
1

We are happy to announce a new version of Documenter.jl! It brings a bunch of new features, improvements, and fixes. It also makes a few breaking changes, so please make sure to consult the CHANEGLOG when you upgrade.

A few highlights of the release:

  • A new frontend

    The HTML front end that Documenter creates has been completely overhauled. Behind the scenes, the Documenter theme is now compiled from Sass files that extend the Bulma CSS framework. To see the new front end in action, you can check out Documenter’s own documentation (v0.24) (vs. old front end (v0.23)).

    In addition, the JS and CSS assets of the HTML front end are more configurable. For example, you can now possible to specify additional languages for the highlighter, choose between KaTeX and MathJax (with the default changed to KaTeX) and easily pass configuration options to them. Finally, you can also set up your own custom remotely hosted assets now.

  • Less Travis and more GitHub Actions.

    Documenter used to be strongly tied to the Travis when it came to deploying the documentation, but no more! The deploydocs function is now much more configurable. If you have custom requirements, it should be easy to tailor everything to your own setup.

    Building on that, Documenter can now build and deploy using with GitHub Actions. If no explicit configuration is given, Documenter will try to autodetect this. For an example setup, see e.g. Literate.jl.

    Currently, only Travis CI and GitHub Actions are supported natively, but implementations for other CI systems are most welcome.

  • Preview builds of pull requests..

    Documenter can now deploy “preview documentation” from pull requests, which is handy when reviewing documentation changes, giving you access to the final rendered document. As a bonus, when building with GitHub Actions, Documenter will send a status update with a link to the documentation!

    To enable this, pass push_preview to the deploydocs function. Documenter will then deploy the rendered documentation under previews/PR## URL, where ## is the pull request number.

    Note: this only work for PRs from branches in the same repository (i.e. not from forks). This is because Documenter needs access to the deploy key, which is not available on forks due to security reasons.

  • Separate doctesting API

    A honorary mention of a feature from Documenter 0.23: Documenter exports a doctest function that can be used to verify (and update!) all doctests without configuring and running a full Documenter setup. This can also be used to integrate doctesting into the normal test suite.

As always, bug reports and feature requests are welcome on the issue tracker. Usage questions can be filed either here on Discourse by attaching the documenter tag or in the #documentation channel on the Julia Slack.

Last but not least: a big big thank you to everyone who contributed code, issues, and feedback that helped make this release happen!

/ Morten and Fredrik

52 Likes
2

Documenter is really great, thank you for your efforts! I have kind of an edge case question: I use it for MakieLayout.jl, whose docs depend on Makie.jl to generate example plots.

Makie doesn’t work on Travis (no GPU), so I have to build locally. Is there an automated way comparable to Travis or Github Actions to compile the docs on my local system and then push them to the gh-pages branch?

Currently, I have duplicated the repo in two folders on my machine and everytime I have a new version I copy all files manually from the build folder of one repo to the dev website folder in the other to push it from there. This is because of the orphan gh-pages branch that needs a completely separate folder structure from the normal repo, but it feels very clunky.

1 Like
3

There is nothing in Documenter at the moment, but it should be possible to use the new DeployConfig interface to implement something for that. It would be a neat feature to have if someone wants to take a stab at implementing it.

4

I just upgraded and all was going great until I tried to host. I got this complaint and cannot find any mention of this anywhere.

┌ Warning: Documenter could not auto-detect the building environment Skipping deployment.
â”” @ Documenter ~/.julia/packages/Documenter/RrEcY/src/deployconfig.jl:41

What have I done wrong?

5

Did you run it locally? Documenter doesn’t deploy then so this warning is expected.

6

OK. Should travis do the right thing anyhow?

7

I had mystery problems with Travis over the last couple days. They seem to be gone and Documenter 2.4 works great. I am using this for the code part of a book project and it is saving me. Thanks!

1 Like