Add `include-read to the events overview; sort core_events` (#12576)

doc/extdev/event_callbacks.rst

@@ -43,6 +43,8 @@ Below is an overview of the core event that happens during a build.
          6. source-read(app, docname, source)
          7. run source parsers: text -> docutils.document
             - parsers can be added with the app.add_source_parser() API
+            - event.include-read(app, relative_path, parent_docname, content)
+              is called for each include directive
          8. apply transforms based on priority: docutils.document -> docutils.document
             - event.doctree-read(app, doctree) is called in the middle of transforms,
               transforms come before/after this event depending on their priority.

sphinx/events.py

@@ -30,22 +30,22 @@ class EventListener(NamedTuple):
 
 # List of all known core events. Maps name to arguments description.
 core_events = {
-    'builder-inited': '',
     'config-inited': 'config',
+    'builder-inited': '',
     'env-get-outdated': 'env, added, changed, removed',
-    'env-get-updated': 'env',
-    'env-purge-doc': 'env, docname',
     'env-before-read-docs': 'env, docnames',
-    'env-check-consistency': 'env',
+    'env-purge-doc': 'env, docname',
     'source-read': 'docname, source text',
     'include-read': 'relative path, parent docname, source text',
     'doctree-read': 'the doctree before being pickled',
     'env-merge-info': 'env, read docnames, other env instance',
+    'env-updated': 'env',
+    'env-get-updated': 'env',
+    'env-check-consistency': 'env',
+    'write-started': 'builder',
+    'doctree-resolved': 'doctree, docname',
     'missing-reference': 'env, node, contnode',
     'warn-missing-reference': 'domain, node',
-    'doctree-resolved': 'doctree, docname',
-    'env-updated': 'env',
-    'write-started': 'builder',
     'build-finished': 'exception',
 }