feat: build reference docs from latest release

[zspriggs]

The basics

• I validated my changes

The details

Resolves

Fixes #10298

Proposed Changes

• The reference docs are now built off a JSON (blockly_api.json) that's generated and committed only during each release.

Added 2 npm scripts, one to docs package.json and one to the root package.json:

• npm run reference:refresh in docs now re-generates blockly_api.json, this is used during the release process but also can be used locally to see API or TSDoc changes reflected when building locally.
• The version script is a lifecycle hook with lerna. It wasn't sufficient to add docs generation as a task in the release process, because the blockly_api.json needs to be generated after the version number is incremented (so that it doesn't pull/display the wrong version) but before the release is fully committed.

To block blockly_api.json from being rebuilt during beta releases, this PR turns off lerna lifecycle hooks during beta releases, so that the new version script never runs. I'm happy to adjust this if it seems like a bad idea to disable the lifecycle hooks. I did it this way because it's one of the simpler options for changing the behavior based on whether it's a beta release or not. We also don't currently use any lerna lifecycle hooks.

• There is a bug in the typedoc plugin that causes localization strings to not work in merge mode. Previously, we were generating the docs straight from source (rather than from the generated JSON) so this didn't come up. It looks like there's already been work on the issue I filed, but the plugin version with the fixes hasn't been released yet. There's some workaround code in typedoc-member-index.mjs that allows our docs to work for now, and it can be deleted once the plugin fix is released.

Reason for Changes

Since docs deployment used to generate the reference docs fresh from main every time, unreleased APIs would leak into the reference docs. Now, since docs are generated from blockly_api.json which is only created/committed on a release, the reference docs always display latest released version of Blockly. This also gives us a way to track API changes.

Test Coverage

Tested the workflows manually as best I could and everything seems to be working, the real test will be whenever we next release Blockly and deploy docs

Documentation

Updated docs readme, and AGENTS.md

Additional Information

• We can't gitignore blockly_api.json because then it couldn't be committed during the release. We could add another PR action that checks to see if this file was edited. I elected not to do that, because I'm hopeful that it's a rare enough scenario that someone will a) regenerate, or manually edit the reference docs and b) commit that generated file that it probably isn't worth adding an action that needs to run on every PR.
• This PR is massive because I'm committing the blockly_api.json. This would otherwise be generated and committed on the next release, which is fine, but without committing it now the docs would be in a state where a deploy would break entirely.
• This PR was LLM assisted

[lizschwab]

Suggested change

	"reference:refresh": "typedoc --options ./typedoc.json --entryPointStrategy resolve --entryPoints ../blockly/core/blockly.ts --includeVersion --json ./blockly_api.json",
	"reference-refresh": "typedoc --options ./typedoc.json --entryPointStrategy resolve --entryPoints ../blockly/core/blockly.ts --includeVersion --json ./blockly_api.json",

We've changed from using colons in script names to using dashes, as nx doesn't play well with the colon syntax. You would also want to update all the references to this command. You might also need to merge in main as the lint:fix script below has been updated to lint-fix as well.

[zspriggs]

Fixed & merged in main!

[lizschwab]

Sorry, forgot to mention this in my earlier review. I'm not sure why this was added, but this is unrelated to the changes you're making and doesn't need to be added.

[zspriggs]

Since I'm using the version script (a lerna lifecycle hook) to handle creating/committing the docs JSON, I needed a way to disable lifecycle hooks when we're doing a beta release. That way, the docs JSON is only generated for full releases.

That said, double checking this made me realize that I can just set --ignore-scripts on the VERSION_COMMAND that's above this line, which feels a little less weird than setting an environment variable. I can also add a comment explaining why the flag is there.