ZIP archive of Dart-SDK API missing details in the right navigation column (v3.1.0 to v.3.2.6)

[hoylen]

The ZIP archive download of the Dart-SDK API (downloaded from https://dart.dev/get-dart/archive) no longer shows navigation links for a library or class.

The documentation ZIP for v3.0.7 and earlier has three columns: a left navigation column listing the libraries, the main content, and a right navigation column listing the library's classes, constants, functions, etc.

The details in the third column is now missing from the recent ZIP files. The right column in ZIP for v3.1.0 and newer (v3.2.6 at the time of writing) does not have any links in the right navigation column. It just shows the name of the library.

• Dart version and tooling diagnostic info
  • Dart 3.2.5 (but it is irrelevant to this issue)
• Whether you are using Windows, macOS, or Linux (if applicable)
  • macOS (archive extracted using command line "unzip" program, as well as double clicking on the ZIP file's icon in the Finder)
• Whether you are using Chrome, Safari, Firefox, Edge (if applicable)
  • Problem occurs with Safari, Firefox and Chrome.

[parlough]

Thanks for reporting this @hoylen! I believe this is because these versions switched to a shared sidebar to reduce the size of generated documentation for large packages and SDKs. As a result, to view the docs with the sidebars, you'd need to serve the contents with an HTTP server.

A quick way to do so would be to use package:dhttpd from the unzipped directory:

dart pub global activate dhttpd
dart pub global run dhttpd

Then open the link it prints out in your browser of choice.

As a note, you can also view the API docs for specific versions on api.dart.dev. For example you can find the API docs for Dart 3.1.1 at https://api.dart.dev/stable/3.1.1/index.html.

If you're able to share, I am curious what you're using the downloaded version of the SDK docs for. Perhaps your workflow can be better supported :)

\cc @srawlins This is due to the sidenav change. Do you think the solution for now is for us to document on dart.dev that it's required to serve the docs?

[srawlins]

Do you think the solution for now is for us to document on dart.dev that it's required to serve the docs?

Yes! Sorry I probably didn't do a good look-around to see what text should be updated.

[hoylen]

So that's why it behaves differently. Thanks for the quick reply.

Definitely documenting the need for a Web server is necessary. But most people won't find the documentation when they come across the problem, or know where to look for it. Two possible solutions to that are:

1. Have the right navigation column show some static HTML text that says something like, "Please serve this documentation from a Web server to use this navigation column" and have it automatically replaced by the real links if it is served up by a Web server. Could some simple JavaScript do that?
2. The API documentation ZIP archive contain a README file to explain how to install it.

My use case is pretty simple: to access the documentation without needing network access. Because a local copy is slightly faster and to avoid wasting bandwidth. Running a local Web server is not a huge problem, though it is less convenient than simply opening up files in a Web browser.

It appears part of the problem is the browser's Cross-Origin Resource Sharing (CORS) mechanism blocking the page from loading the index.json and sidebar HTML files. I'm not familiar with how CORS works with "file:" URIs or what has changed from the JavaScript generated for the older documentation. Has anyone looked into that (as an alternative to running a Web server)?

[hoylen]

I now see why CORS is causing the problem. The new docs.dart.js file invokes XMLHttpRequest and fetch, both of which involve CORS. Browser implementations differ on how CORS behaves with "file" scheme URIs, but they err on the side of security and usually block the requests (even though you might assume a file loading another file should be ok). There is a workaround flag for running Google Chrome, but it is inconvenient and risky to use.

The older version of docs.dart.js does not use XMLHttpRequest. However, it did use fetch. But I haven't looked into why the old invocation of fetch appears to work and the new one does not.

Sounds like serving up the files with a local Web browser is the best approach... as long as the user downloading the ZIP file somehow knows that is how it must be used.