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
deploydocsfunction 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
deploydocsfunction. Documenter will then deploy the rendered documentation under
##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
doctestfunction 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