When documentation can't be generated, considering the redirecting behavior, some packages documentations becomes inaccessible

[mateusfccp]

Derived from #8159.

pub.dev does not generate documentation for all published versions. Instead, it generates the documentation according to some rules. I'm not sure if these rules are right, but this is what I perceived from looking at the packages:

• It will generate documentation for the latest two versions of the greatest major version.
• It will generate documentation for the latest version of every major version.

For all the other versions, if you try to access the corresponding documentation, it will be redirected to the latest available.

Now comes the problem.

Sometimes, documentation generation fails. When this happens, documentation of the specific version that failed becomes inaccessible. However, the rules above doesn't consider failure, which leads to some major versions becoming completely inaccessible.

For instance, the package analyzer. The latest three versions (6.11.0, 6.10.0 and 6.9.0) failed to generate documentation. The last version that had a documentation successfully generated was 6.8.0.

However, considering the rules above, pub.dev does not try to generate this documentation anymore.

Thus, every time anyone tries to access any documentation of the analyzer package latest stable (any 6.x.x), they will be redirected to a failed documentation, making it completely inaccessible.

The only workaround for this is to clone the package and generate the documentation manually with dart doc, which is far from ideal.

There are many ways to solve this. This is what I think would be a good approach:

• When a documentation generation fails, try to generate the previous one. In this case of analyzer, it would try to generate for 6.11.0, failing, then 6.10.0, failing, then 6.9.0, failing, then 6.8.0, succeeding and stopping.

[isoos]

However, the rules above doesn't consider failure, which leads to some major versions becoming completely inaccessible.

We are really happy to take feedback and point out bugs, but please, if possible, do not speculate on the internals, as it will need extra effort to dig it up and refute the claims. In this case, we do consider failure and base our selection on it (as I've said in the previously opened issue, the selection criteria is a bit more complex):

https://github.com/dart-lang/pub-dev/blob/master/app/lib/task/backend.dart#L1094-L1100

Note: The failure of analyzer is an entirely different issue than the documentation redirects, and solving that requires a different focus. It is also worth to note that once we have the new stable SDK out, it will resolve itself.

[isoos]

My apologies: looking at the code, it does really consider just the finished state and not the success state. I thought we do consider successful dartdoc completion, and maybe we should.

E.g. in this case https://pub.dev/documentation/analyzer/5.13.0/ has a completed documentation, which may be worth to switch to.

[mateusfccp]

Please, if possible, do not speculate on the internals, as it will need extra effort to dig it up and refute the claims.

I'm sorry, I won't do it anymore.

Note: The failure of analyzer is an entirely different issue than the documentation redirects, and solving that requires a different focus. It is also worth to note that once we have the new stable SDK out, it will resolve itself.

I know this much, but the combination of the two points (the fact that is failing + the fact that it won't generate documentation for non-failing versions) makes it impossible for anyone to check the documentation of 6.x unless they compile the documentation manually in their local machine.

This is why I made this suggestion.

E.g. in this case https://pub.dev/documentation/analyzer/5.13.0/ has a completed documentation, which may be worth to switch to.

It's a possibility, but considering that it's a considerably old version and a different major version, there are probably relevant differences. For some cases it may work, while for others not so much.