The documentation has broken links from external sites

[gaaclarke]

Twice today I've clicked links to flutter documentation from outside of the Flutter website and found broken links. The last broken link was https://api.flutter.dev/flutter/widgets/UniqueKey-class.html as see in the following StackOverflow answer https://stackoverflow.com/a/60248462/20063373.

It appears the proper URL for that class is https://api.flutter.dev/flutter/foundation/UniqueKey-class.html .

Did that class get moved then the automatic documentation generation not put a redirect to the new location? We should be tracking hits to broken links so that we can find them and replace them with the proper redirects when this happens.

cc @Hixie

[Hixie]

@jcollins-g @srawlins @gspencergoog any idea how we can address this? When people move something between libraries I don't see how the tool can figure that out. We could do it retroactively, by just keeping an eye on 404s and putting in redirects as we find them, but that would require cherrypicks or something since we'd need to be updating the stable docs too...

[gspencergoog]

I wonder if we can do the redirects as part of the server configuration instead of part of the documentation source? Then we could automate updating the server config out of sync with releases. The config could come from a file in a repo somewhere so that the changes were versioned and controlled. It would be important to vet those redirects, since otherwise they could be a security issue. I'm not at all clear on what the actual mechanisms involved here would be, though (probably something to do with the Firebase projects that host the docs web pages).

[gaaclarke]

I don't see how the tool can figure that out.

Technically the documentation generation tool could determine redirects by building its documentation by considering the whole git history, not just HEAD. It would be a bit of an investment to implement though since it would need to:

1. be able to detect moves of classes (a - class Foo and a + class Foo in the same commit)
2. create a caching mechanism so that it doesn't always have to replay the whole git history each generation

[gaaclarke]

Another option is to place the version of flutter in the URL:
https://api.flutter.dev/flutter/2.0.0/foundation/UniqueKey-class.html

There can also be
https://api.flutter.dev/flutter/current/foundation/UniqueKey-class.html

Then it may be easier to build a script that looks for different file structure for each version to create redirects.

[Hixie]

@gaaclarke We want to avoid having more than one (well, two, if you count the master branch API docs) version of the API docs because we noticed a huge antipattern in lots of other SDKs wherein they have lots and lots of versions of the API docs and people often end up looking at old versions (e.g. due to following links or search engines not noticing they're old or whatever).

@itsjustkevin I'm not sure this belongs in flutter/website, it's about the API docs not the docs.flutter.dev site.

In the absence of a better solution, can we just get the 404 logs and regularly set up redirects?

[itsjustkevin]

@Hixie thanks for pointing this out. Do we want to move it back, and do we have someone who wants to take a look at this issue?

cc: @atsansone

[sfshaza2]

No, sorry, this absolutely belongs in the flutter/flutter repo. :)

[a-siva]

@goderbauer what is the dart-dependency part in this ?

[goderbauer]

The dart-dependency here was: Can anything be done in the DartDoc tool to help with this?

[a-siva]

The dart-dependency here was: Can anything be done in the DartDoc tool to help with this?

@srawlins is this something that the Dart Doc tool could help with ?

[srawlins]

Yes, we could add any number of features to generate additional redirecting HTML files.

E.g. in a dartdoc_options.yaml file, could specify e.g.:

redirects:
  - from: foundation/UniqueKey-class.html
  - to: widgets/UniqueKey-class.html

Or maybe an annotation on UniqueKey class, @IUsedToLiveIn(['package:flutter/foundation.dart', ...]).

If the flutter team is interesting in maintaining such a redirect list or set of annotations. As for tooling to automatically detect old locations and redirect to new locations, that would be outside dartdoc's purview.