Why documentation links are often broken?

General Usage
1

It is quite common to find broken Julia package documentation links, like this one (see docs stable link in the page):

Why is this and is there a workaround?

2

I don’t have an immediate fix or workaround, but here’s the why…

Creating documentation requires running code. Code that might break. And hosting the generated website somewhere. Hosting that might go away. Both things require some maintenance.

In this case, its docs are pointing at JuliaHub’s doc generation service: JuliaHub

If you click the little ⓘ button, you can get information about what happened when it tried to build. Clicking the logs shows:

┌ Error: `using Tk did not succeed.`
│   exception =
│    LoadError: InitError: Tk.TclError("error initializing Tk: no display name and no \$DISPLAY environment variable")
│    during initialization of module Tk
│    in expression starting at /juliateam/.julia/packages/Tk/c8ZUf/src/Tk.jl:94
└ @ DocumentationGenerator ~/.julia/packages/DocumentationGenerator/12evC/src/DocumentationGenerator.jl:33

In other words, Tk.jl doesn’t like running in a “headless” environment that is common to CI systems and doc building services.

2 Likes
3

Not applicable in this case but
a common reason docs are often broken is PkgTemplate.jl will insert doclinks for you
but setting up docs to be hosted on github pages requires manual work of pushing keys.
And it’s quite fiddly as you might mistakenly insert newlines etc (though DocumenterTools.jl tries as hard as possible to make it easy, and it definately makes it easier)
So the default state of docs links on new packages is broken.

Older packages had docs working on TravisCI that broke when TravisCI went away

2 Likes
4

Thank you for your in-depth responses.
Would it be a good idea to always create a backup pdf file? At least we would have something to chew…