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.

43 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!

4 Likes

Small follow-up ANN: Documenter 0.27.1 just got tagged. It brings a few fixes to the version warning feature. But as a bigger change, it also now uses @cormullion’s JuliaMono as the default monospace font!

Note that if you have Documenter = "0.27" in your docs/Project.toml, the update should happen automatically.

7 Likes

I have been intentionally very conservative with what goes into a patch release. The reason is that with the standard setup the latest patch version gets used automatically on CI, and so it is easy to silently and automatically break the deployed documentation. E.g. in case of 0.27, e.g. the KaTeX library had a major version bump, which might break the rendering of some more complex equations.

As for 1.0 – yes, that would be good. It would allow for a bit more nuance in terms of versioning (more complex docs probably want to restrict to a minor version of Documenter, but simpler ones are probably fine with the standard a major version restriction). But there is a backlog of things that should be done before we commit to 1.0 (e.g. moving the Markdown backend out of Documenter, revising the documentation).

8 Likes

Maybe edit this text (or make it bold)? I got bitten by it:

Documenter 0.27.2 (changelog) and 0.27.3 (changelog) are released with miscellaneous fixes.

I just wanted to highlight one new feature which is the ability to deploy to the “root” instead of to a versioned folder. Previously it was only possible to deploy to a subfolder, e.g. v1.2.3 or latest, but that only makes sense for versioned project (such as packages). This feature is used already for https://juliadocs.github.io/ (which thus previously was deployed to https://juliadocs.github.io/latest).

6 Likes

Documenter versions 0.27.4 (changelog) and 0.27.5 (changelog) are released.

I want to highlight some new features that I personally think are pretty neat:

  • @repl and @example blocks now support colored text output much in a terminal (thanks @kimikage).
  • Experimental support for pregeneration of code syntax highlighting (e.g. during build instead of “live” in the browser). At the cost of slightly larger HTML pages users without JavaScript enabled can now also enjoy code syntax highlighting. However, the feature I am most excited about is that it makes it possible to use an improved highlighter.
  • Varions fixes to @repl and @example blocks: correct LineNumberNodes for more realistic output from e.g. logging macros and error messages, better scrubbing of the sandbox module used by Documenter to evaluate code.
13 Likes