Missing documentation for env-get-updated

[lmmx]

Is your feature request related to a problem? Please describe.

I was reading through the extension API docs section on 'core events' (source: https://github.com/sphinx-doc/sphinx/blob/4.x/doc/extdev/appapi.rst) and taking some notes.

The page includes an informative walkthrough of the order in which these events take place during a Sphinx run, and then says

Here is a more detailed list of these events.

I counted 15 events in the list when I took my notes:

1. config-inited (app, config)
2. builder-inited (app)
3. env-get-outdated (app, env, added, changed, removed)
4. env-before-read-docs (app, env, docnames)
5. (Looping through docs begins) env-purge-doc (app, env, docname)
6. ...(if doc changed and not removed) source-read (app, docname, source)
7. ...(called in the middle of transforms) doctree-read (app, doctree)
8. (Looping through docs finished) env-merge-info (app, env, docnames, other)
9. env-updated (app, env)
10. env-get-updated (app, env)
11. env-check-consistency (app, env)
12. (Looping through updated docs begins) doctree-resolved (app, doctree, docname)
13. ...(in the event that any reference nodes fail to resolve) missing-reference (app, env, node, contentnode)
14. ...or warn-missing-reference (app, domain, node)
15. (After output files are generated) build-finished (app, exception)

and the "more detailed list" had 18, so I presumed there'd be 3 extra I hadn't seen in the 'walkthrough' (since 18 - 15 = 3).

However the list that follows had 4 more, so I was confused.

• These were object-description-transform, html-collect-pages, html-page-context, linkcheck-process-uri

The reason was that the more detailed list omits env-get-updated (step number 10 in my notes), so there are in fact 19 in total (and 19 - 15 = 4).

The core events are given in events.py, and the comment there says these are "all known core events", however there are only 15.

The 4 not in the code's list of "all known core events" are the same 4 as the ones not in the 'walkthrough'.

Describe the solution you'd like

• I'm not sure there's anything wrong with the "more detailed list" (adding the 4 extra functions), but if possible, I'd make it clearer that these 4 are not "core events" but are in fact loaded from sphinx.directives, sphinx.builders.html and sphinx.builders.linkcheck modules
• I think there is a mistake in the source file doc/extdev/appapi.rst, it should not omit env-get-updated

Describe alternatives you've considered

One alternative I've considered is that this was a deliberate omission. If so, that's fine, but in case it wasn't then I hope this is helpful to improve the docs.

From what I can see in the collectors module, env-get-updated triggers EnvironmentCollector.get_updated_docs whose docstring says:

Return a list of docnames to re-read.
        This methods is called after reading the whole of documents (experimental).

So my suggestion for a new entry for docs/extdev/appapi.rst would be something like:

.. event:: env-get-updated (app, env)

   
   This method is called after reading all documents, and after env-updated
   has returned a list of docnames to re-read.

   .. versionadded:: ?

   .. versionchanged:: ?
      ?

• I'm not sure from viewing the git blame whether this was added around version 1.5 or prior (left it as "?")
• I'm not sure if the behaviour has changed in a significant way that should be documented with versionchanged (left as "?")

[AA-Turner]

Added in #12446.

A