ANN: Documenter 0.27

Hey everyone,

version 0.27 of Documenter.jl just got released. It brings a bunch of bug fixes and general improvements, but also a new feature:

Warnings and SEO for outdated docs

Documenter now injects a tiny piece of JavaScript into its HTML output, which checks whether there is a newer version of the documentation available. If so, we display a prominent warning and add a meta tag that stops search engines from indexing the page.

Adding this warning to existing docs is a manual process, but should be as easy as calling

using DocumenterTools
OutdatedWarning.generate("/path/to/your/docs")

on e.g. the gh-pages branch in your package’s repository. Note that you’ll need to figure out which of these changes to check in; I’d suggest running it on the entirety of the docs just before tagging a new version (which has docs built with the Documenter 0.27).

Check out old versions of the Julia docs if you want to see this feature in action!

If you’re a package author, we urge you to upgrade to Documenter 0.27 as soon as possible and maybe even run the OutdatedWarning.generate process on your docs to (hopefully) reduce user confusion and keep search results more relevant.

As always, please file bug reports and feature requests on GitHub. Usage questions are welcome on Discourse and in the #documentation channel on the Julia Slack.

34 Likes

This single feature will have a large effect on reducing a common pain point for new users. Thanks a lot!

7 Likes

Completely agree. This great!

How do I convince github actions to use .27. I tried putting

[compat]
Documenter = "0.27"

in docs/Project.toml

and the run failed with

Run julia --project=docs/ -e 'using Pkg; Pkg.develop(PackageSpec(path=pwd())); Pkg.instantiate()'
4
Path `/home/runner/work/SIAMFANLEquations.jl/SIAMFANLEquations.jl` exists and looks like the correct package. Using existing path.
5
   Resolving package versions...
6
  Installing known registries into `~/.julia`
7
       Added registry `General` to `~/.julia/registries/General`
8
ERROR: Unsatisfiable requirements detected for package DocumenterLaTeX [cd674d7a]:
9
 DocumenterLaTeX [cd674d7a] log:
10
 ├─possible versions are: 0.1.0-0.2.0 or uninstalled
11
 ├─restricted to versions * by an explicit requirement, leaving only versions 0.1.0-0.2.0
12
 └─restricted by compatibility requirements with Documenter [e30172f5] to versions: uninstalled — no versions left
13
   └─Documenter [e30172f5] log:
14
     ├─possible versions are: 0.19.0-0.27.0 or uninstalled
15
     └─restricted to versions 0.27 by an explicit requirement, leaving only versions 0.27.0

When I leave this out of docs/Project.toml I wind up with version .25.2

DocumenterLaTeX is a paused experiment and you shouldn’t need it with Documenter >= 0.26. Try to remove that first.

2 Likes

Is there a section of the Documenter.jl documentation explaining the feature? I couldn’t find it, and was wondering what exactly is the path to the documentation. You mention “gh-pages” so this is the branch on github where the documentation is committed?

Is it possible to add a distinction between “old version of documentation” vs “documentation is up-to-date, but for an old package version”? These two may imply very different things from a user’s POV: docs are old => always go to the updated ones; docs are for an old version => stay there if this is the version you need.
For example, julia 1.0-1.5 docs would show the “old docs” message, while julia 0.x “docs fine, but old version”.

1 Like

That did it. I clearly missed the memo on DocumenterLaTeX.
Thanks.

OutdatedWarning.generate

Yea, you give the path to the folder where you have checked out the gh-pages branch.

For Julia 1.X there is just one document. So even though there is docs for 1.0.5 specifically you should always read the latest one (hence why the default url is just /v1 and not v1.6 for example).

1 Like

Julia itself was just an example, the general point still stands.
If MyPackage latest version is 0.5.5, then docs for 0.5.1-0.5.4 should show “old docs” label, while 0.1-0.4 should show “old package version” label. These two meanings are different for those who use e.g. the 0.3 version and doesn’t want to upgrade.

I was suggesting you should do the same. Do you really want user to use and for you to support multiple breaking releases? If you indeed are reading the correct documentation then you can just ignore the warning.

Would a wording like

This documentation is not for the latest version.

be better and be applicable in both cases?

Thank you @fredrikekre . Do you have an example package with the warning enabled in the docs/make.jl file?

It is enabled by default for new documentation generated using Documenter >= 0.27. The DocumenterTools.OutdatedWarning.generate function I linked to above is for adding the warning to old versions that have already been built with Documenter < 0.27.

1 Like

Yes, I think it is better and is never misleading.

What are the breaking changes in v0.27? I don’t see any in the ChangeLog. Also, can we have a v1.0 release as next breaking release so that new features don’t make a minor bump? :slightly_smiling_face:

After the rant, thanks for work on the package!

3 Likes