ANN: Documenter 1.0

[mortenpi]

I am very pleased to announce the release of Documenter 1.0. It finally unleashes a bunch of great improvements and excellent contributions that have been “locked up” on master for the past year or so.

I am slightly less pleased to announce that, true to its nature as a major version change, the release does contain a few non-trivial breaking changes that will likely affect your documentation builds, and you will probably need to update your make.jl files. Please see the release notes for details and instructions on how to upgrade.

I do want to thank everyone for their patience, which allowed us to get a big set of breaking changes all bunched up into a single release, reducing the disruption and breaking-release-churn in the ecosystem. I do hope that we will stay on 1.x for a while now, and will be able to have much more frequent non-breaking releases.

For most docs it should be safe to set Documenter compat to Documenter = "1" in docs/Project.toml. Although you may want to double-check what SemVer guarantees mean in the context of Documenter, especially if you do non-trivial stuff in your docs/make.jl.

As always, if you encounter any issues or errors, please don’t hesitate to open issues on the Documenter issue tracker.

Happy documenting!

Release highlights

First, I want to thank everyone who has contributed to Documenter, via PRs, issues, feedback, and helped us to get to this release! Here I just want to highlight a few of the many-many changes and improvements that have happened over the past year:

New search interface

For the past several months, as part of his Summer of Code project, @Hetarth02 worked on improving the UI and UX of Documenter’s search, and Documenter now ships with a much more polished UI:

Under the hood, he also changed the JS search engine to MiniSearch, which is more actively maintained compared to the previously used lunr.js. You can also read Hetarth’s GSoC submission for more details on this work.

Link to repository

Tiny, but much-asked feature: Documenter now includes a link to the landing page of your package repository. Tangentially related to this is that Documenter is now much smarter and more consistent about handling the different remote links (page edit and Julia source links; this will also fix the source links of standard library functions in the Julia manual).

PDF improvements

@odow contributed heaps of great fixes and improvements to the PDF/LaTeX backend, such as improved admonition, table, and code block styling and handling, which should come to your Julia Manual PDF soon.

Strict by default

Documenter has quite a few checks to make sure that the generated documentation is not broken in some way. However, those only break builds if you set strict = true. When people don’t explicitly do that, they generally miss the warnings on documentation CI, and end up shipping half-broken documentation sites.

To encourage people to fix the issues as they come up, Documenter now runs in the strict = true mode by default (although that keyword has been removed; but you can still explicitly opt out from some or all checks with the new warnonly keyword).

Note that several new checks that have also been added, which may cause previously warning/error-free builds to error now.

Catch large HTML pages

One silent issue that quite a few documentation sites have is that their generated content (e.g. figures and other at-example block outputs) is leading to HTML pages that can be tens or even hundreds of megabytes, which in turn leads to a bad experience for the reader who opens it in the browser.

To nudge the authors to address this, Documenter will now by default complain if the generated examples pages are too big (the behavior can be controlled with the size_threshold* options). When it comes to generated images, like plots, Documenter will now write them into separate files, automatically helping reduce the size of the HTML files.

[tim.holy]

This looks amazing, can’t wait to try it out! Thanks to the maintainers and the many who contributed.

[DanielVandH]

Amazing work! Great job. Especially like the new search - good job @Hetarth02

[cgarling]

Noticed this today and have been updating a few of my packages. Hasn’t been too bad so far; although I encountered several of the breaking changes, the provided changelog has been helpful in transitioning. Quite a few nice features to justify the update. Thanks!

[goerz]

For anyone who is using the DocumenterCitations plugin to add bibliographic references to their documentation: We also just released DocumenterCitations 1.2.0 to be compatible with Documenter 1.0.

A notable breaking change in Documenter 1.0 that affects any users of DocumenterCitations is that plugin objects now have to be passed to makedocs via a plugins keyword argument. For the old Documenter 0.27 / DocumenterCitations 1.1 your docs/make.jl file would have looked like this:

using DocumenterCitations

bib = CitationBibliography(
    joinpath(@__DIR__, "src", "refs.bib");
    style=:numeric
)
makedocs(bib, ...)  # positional argument

With the new Documenter 1.0 / DocumenterCitations 1.2 you will have to change this to

makedocs(; plugins=[bib], ...)

Apart from compatibility with Documenter 1.0, changes since the original announcement include a significantly improved :alpha citation style that avoids duplicate labels and better support for preprint servers like arXiv. See NEWS.md for more details.

[jeremiedb]

Cograts on the v1 milestone!

Regarding warnonly, I resorted to using it in order to have the CI continue to work for my package. This was due to docstring not included in the manual. Is there a recommended practice for situation where on one hand I want to include docstring to internal functions (in order to have the source code documented), but not necessarily include them in the generatd user facing manual?

[wsshin]

I didn’t notice this in the documentations generated by the previous versions of Documenter, but maybe I was just ignorant: what is the upward arrowhead at the top-right corner, indicated by the red circle in the screenshot below?

Clicking it turns it to a downward arrowhead, but nothing happens.

[DanielVandH]

That collapses the docstrings - try it on this page Public API · Documenter.jl (hovering over the arrow also shows this).

[franckgaga]

I love the the new version of Documenter. It’s really helpful for the development of my package. Keep up the good work !

Francis

[gdalle]

Gotta love how a bold breaking change (strict by default) is forcing the entire ecosystem to get their mess together and document stuff.
This is a non-negligible contribution to making all of Julia more reliable. Thank you!

[mortenpi]

@jeremiedb

Is there a recommended practice for situation where on one hand I want to include docstring to internal functions (in order to have the source code documented), but not necessarily include them in the generatd user facing manual?

I’d say the current practice is to have an “internals” page where you include those docstrings. You can also hide that from the navigation menu with Documenter.hide if you want. That’s how Documenter itself does it, e.g. Anchors · Documenter.jl

[EssamWisam]

Fantastic! Can’t wait for the release where syntax highlighting will be finally improved.

[Hetarth02]

Thank you, glad you liked the new search. I hope to contribute more.

[heliosdrm]

@mortenpi

To nudge the authors to address this, Documenter will now by default complain if the generated examples pages are too big (the behavior can be controlled with the size_threshold* options).

May those options (e.g. setting a custom threshold) be used when calling makedocs? I found a reference to size_threshold in the docs of Documenter.HTMLWriter, but I don’t know how to use it. I’m just using makedocs as explained in the guide of Documenter, and it seems that size_threshold is not a valid keyword for that function.