Docs for interpreting "Unsatisfiable requirement"

[timholy]

A lot of people seem to struggle with understanding what the error message means and how to fix it. I figured it was time to have some docs about this.

The approach I've taken here is one step shy of a real doctest: I am trying to generate the actual error message, though its form is untested due to the difficulty of setup and the fact that the means to generate the error is unrelated to how this would be triggered in ordinary usage. (Documenter doesn't seem to let you test the output without showing the input, and here I don't want to show the input.) I then repeat the message via copy/paste in chunked form as I go through the pieces stepwise and help interpret what they mean. If someone changes the presentation of the message without updating the documentation, these two will be desynchronized, but at least readers might be able to detect that there is something wrong and so we should hear about it fairly quickly.

This currently doesn't do the right thing when building: I get

┌ Warning: failed to run `@example` block in src/managing-packages.md:289-291
│ ```@example conflict
│ resolve_tst(deps_data, reqs_data)   # hide
│ ```
│   value =
│    Unsatisfiable requirements detected for package C [c99a7cb2]:
│     C [c99a7cb2] log:
│     ├─possible versions are: [0.1.0-0.1.1, 0.2.0] or uninstalled
│     ├─restricted by compatibility requirements with B [f4259836] to versions: 0.2.0
│     │ └─B [f4259836] log:
│     │   ├─possible versions are: 1.0.0 or uninstalled
│     │   └─restricted to versions * by an explicit requirement, leaving only versions 1.0.0
│     └─restricted by compatibility requirements with A [29c70717] to versions: 0.1.0 — no versions left
│       └─A [29c70717] log:
│         ├─possible versions are: 1.0.0 or uninstalled
│         └─restricted to versions * by an explicit requirement, leaving only versions 1.0.0
└ @ Documenter.Expanders ~/.julia/packages/Documenter/hhZV5/src/Expanders.jl:564

which is an error message that I want to appear in the documentation, but instead it gets shown here and instead the doc page contains

resolve_tst(deps_data, reqs_data)   # hide

which is definitely not what I was trying to achieve. Does Documenter need @example_throws?

[fredrikekre]

Does Documenter need @example_throws?

Maybe something like that, or just assume errors are intentional. For jldoctest blocks that is the default.

For this example you can maybe use a hidden try-catch, and end with something like sprint(showerror, err).

[timholy]

Thanks @fredrikekre, that was super-helpful. I've adopted a slightly more complicated example that is hopefully more typical of the most common kind of errors, and added a section on how one goes about resolving these errors.

[timholy]

Preview: https://julialang.github.io/Pkg.jl/previews/PR1798/

Once this finishes building, in particular click "Managing packages" -> "Interpreting and resolving version conflicts" as well as "Compatibility" -> "Fixing conflicts" (these two sections link to one another).

[timholy]

(I shouldn't have done a force push after @fredrikekre's approval, but all I did was eliminate a single line break.)

[KristofferC]

Should this mention the case where you might still be stuck at 0.1 due to some other package also holding D back, thereby not knowing if 0.2 is compatible with B or not?

[timholy]

Good idea, see if you think this is OK.