collect MDN API information

[devoncarew]

• contribute a script which scrapes https://developer.mozilla.org/en-US/docs/Web for interface and interface member api documentation
• write that info into a json file in this repo

This PR collects the info that we'd later want to write into the API dart docs for package:web; some work towards #122.

---

• I’ve reviewed the contributor guide and applied the relevant portions to this PR.

Contribution guidelines:

• See our contributor guide for general expectations for PRs.
• Larger or significant changes should be discussed in an issue before creating a PR.
• Contributions to our repos should follow the Dart style guide and use dart format.
• Most changes should add an entry to the changelog and may need to rev the pubspec package version.
• Changes to packages require corresponding tests.

Note that many Dart repos have a weekly cadence for reviewing PRs - please allow for some latency before initial review feedback.

[kevmoo]

Oooo!

[devoncarew]

It looks like the json file's too large to display as part of the PR. Here's the first few lines of it:

{
  "__meta__": {
    "source": "[MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web)",
    "license": "[CC-BY-SA 2.5](https://creativecommons.org/licenses/by-sa/2.5/)"
  },
  "ANGLE_instanced_arrays": {
    "docs": "The **`ANGLE_instanced_arrays`** extension is part of the WebGL API and allows to draw the same object, or groups of similar objects multiple times, if they share the same vertex data, primitive count and type.\n\nWebGL extensions are available using the `WebGLRenderingContext.getExtension()` method. For more information, see also Using Extensions in the WebGL tutorial.\n\n**Note:** This extension is only available to WebGL1 contexts. In WebGL2, the functionality of this extension is available on the WebGL2 context by default and the constants and methods are available without the \"`ANGLE`\" suffix.\nDespite the name \"ANGLE\", this extension works on any device if the hardware supports it and not just on Windows when using the ANGLE library. \"ANGLE\" just indicates that this extension has been written by the ANGLE library authors.\n\nSee also https://developer.mozilla.org/en-US/docs/Web/API/ANGLE_instanced_arrays."
  },
  "AesCbcParams": {
    "docs": "The **`AesCbcParams`** dictionary of the Web Crypto API represents the object that should be passed as the `algorithm` parameter into `SubtleCrypto.encrypt()`, `SubtleCrypto.decrypt()`, `SubtleCrypto.wrapKey()`, or `SubtleCrypto.unwrapKey()`, when using the AES-CBC algorithm.\n\nSee also https://developer.mozilla.org/en-US/docs/Web/API/AesCbcParams."
  },
  "Accelerometer": {
    "docs": "**Experimental:** **This is an experimental technology**\n\nCheck the Browser compatibility table carefully before using this in production.\n\nThe **`Accelerometer`** interface of the Sensor APIs provides on each reading the acceleration applied to the device along all three axes.\n\nTo use this sensor, the user must grant permission to the `'accelerometer'`, device sensor through the Permissions API.\n\nThis feature may be blocked by a Permissions Policy set on your server.\n\nSee also https://developer.mozilla.org/en-US/docs/Web/API/Accelerometer.",
    "properties": {
      "x": "Returns a double containing the acceleration of the device along the device's x axis.",
      "y": "Returns a double containing the acceleration of the device along the device's y axis.",
      "z": "Returns a double containing the acceleration of the device along the device's z axis."
    }
  },
  "AbortController": {
    "docs": "The **`AbortController`** interface represents a controller object that allows you to abort one or more Web requests as and when desired.\n\nYou can create a new `AbortController` object using the `AbortController()` constructor. Communicating with a DOM request is done using an `AbortSignal` object.\n\nSee also https://developer.mozilla.org/en-US/docs/Web/API/AbortController.",
    "properties": {
      "abort": "Aborts a DOM request before it has completed. This is able to abort fetch requests, consumption of any response bodies, and streams.",
      "signal": "Returns an `AbortSignal` object instance, which can be used to communicate with, or to abort, a DOM request."
    }
  },
...

[srujzs]

This is great, thanks Devon!

[srujzs]

Is there any benefit to writing out the json and then consuming it later versus just having the node information in memory? If this is to just visualize the contents for now, then ignore this comment.

[devoncarew]

Collecting the info from MDN is ~slower (around 20s) and could fail depending on networking conditions. My idea was to separate collecting the info (something you might run ~monthly) from using that info to generate docs + generated code (something you do on every commit).

It's probably not critical to separate these things out, but is what I was going for w/ this PR.

[srujzs]

Ah, I see, I didn't realize it was that slow. Then yes, let's avoid this slowing down iteration of the generation script if it's that significant.

I'm a little concerned on how to keep this updated (both in terms of the the script you added and the docs in the output files) if we aren't running the script to run the docs when we generate code regularly. This may not be a big issue after the original generation, but we're likely to have stale documentation. For this CL and the following ones, it's okay to not worry about this for now.

[devoncarew]

It looks like the system-of-record for this information are markdown files (e.g. https://github.com/mdn/content/blob/main/files/en-us/web/api/htmlmediaelement/src/index.md?plain=1). We may want to look into reading from them directly instead of from the served html.

[kevmoo]

It looks like the system-of-record for this information are markdown files (e.g. https://github.com/mdn/content/blob/main/files/en-us/web/api/htmlmediaelement/src/index.md?plain=1). We may want to look into reading from them directly instead of from the served html.

Big fan of separating download from generate. Makes iterative hacking on the generator a LOT easier.