✨ NEW: Emits sphinx include-read event (#887)

Adds emission of Sphinx `include-read` events while processing include directives
See: https://www.sphinx-doc.org/en/master/extdev/appapi.html#event-include-read

Co-authored-by: Chris Sewell <chrisj_sewell@hotmail.com>

myst_parser/mocking.py

@@ -381,6 +381,22 @@ def run(self) -> list[nodes.Element]:
                 4, f'Directive "{self.name}": error reading file: {path}\n{error}.'
             ) from error
 
+        if self.renderer.sphinx_env is not None:
+            # Emit the "include-read" event
+            # see: https://github.com/sphinx-doc/sphinx/commit/ff18318613db56d0000db47e5c8f0140556cef0c
+            arg = [file_content]
+            relative_path = Path(
+                os.path.relpath(path, start=self.renderer.sphinx_env.srcdir)
+            )
+            parent_docname = Path(self.renderer.document["source"]).stem
+            self.renderer.sphinx_env.app.events.emit(
+                "include-read",
+                relative_path,
+                parent_docname,
+                arg,
+            )
+            file_content = arg[0]
+
         # get required section of text
         startline = self.options.get("start-line", None)
         endline = self.options.get("end-line", None)

tests/test_sphinx/sourcedirs/includes/index.md

@@ -1,5 +1,8 @@
 # Main Title
 
+```{include} ../include_from_rst/include.md
+```
+
 ```{include} include1.inc.md
 ```
 

tests/test_sphinx/test_sphinx_builds.py

@@ -8,10 +8,14 @@
 (e.g. converting `<div class="section">` to `<section>`)
 """
 
+from __future__ import annotations
+
 import os
 import re
+from pathlib import Path
 
 import pytest
+import sphinx
 from docutils import VersionInfo, __version_info__
 
 SOURCE_DIR = os.path.abspath(os.path.join(os.path.dirname(__file__), "sourcedirs"))
@@ -583,3 +587,45 @@ def test_texinfo(app, status, warning):
     assert "build succeeded" in status.getvalue()  # Build succeeded
     warnings = warning.getvalue().strip()
     assert warnings == ""
+
+
+@pytest.mark.skipif(
+    sphinx.version_info < (7, 2, 5), reason="include-read event added in sphinx 7.2.5"
+)
+@pytest.mark.sphinx(
+    buildername="html",
+    srcdir=os.path.join(SOURCE_DIR, "includes"),
+    freshenv=True,
+)
+def test_include_read_event(app, status, warning):
+    """Test that include-read event is emitted correctly."""
+
+    include_read_events = []
+
+    def handle_include_read(
+        app, relative_path: Path, parent_docname: str, content: list[str]
+    ) -> None:
+        include_read_events.append((relative_path, parent_docname, content))
+
+    app.connect("include-read", handle_include_read)
+    app.build()
+    assert "build succeeded" in status.getvalue()  # Build succeeded
+    warnings = warning.getvalue().strip()
+    assert warnings == ""
+    expected = [
+        ("../include_from_rst/include.md", "index"),
+        ("include1.inc.md", "index"),
+        (os.path.join("subfolder", "include2.inc.md"), "include1.inc"),
+        ("include_code.py", "index"),
+        ("include_code.py", "index"),
+        ("include_literal.txt", "index"),
+        ("include_literal.txt", "index"),
+    ]
+    expected_events = []
+    for include_file_name, parent_docname in expected:
+        with open(os.path.join(SOURCE_DIR, "includes", include_file_name)) as file:
+            content = file.read()
+        expected_events.append((Path(include_file_name), parent_docname, [content]))
+    assert len(include_read_events) == len(expected_events), "Wrong number of events"
+    for evt in expected_events:
+        assert evt in include_read_events

tests/test_sphinx/test_sphinx_builds/test_includes.html

@@ -8,6 +8,19 @@ <h1>
       ¶
      </a>
     </h1>
+   </section>
+   <section id="markdown">
+    <h1>
+     Markdown
+     <a class="headerlink" href="#markdown" title="Permalink to this heading">
+      ¶
+     </a>
+    </h1>
+    <p>
+     <a class="reference external" href="http://example.com/">
+      target
+     </a>
+    </p>
     <section id="a-sub-heading-in-include">
      <span id="inc-header">
      </span>

tests/test_sphinx/test_sphinx_builds/test_includes.xml

@@ -2,6 +2,12 @@
     <section ids="main-title" names="main\ title">
         <title>
             Main Title
+    <section ids="markdown" names="markdown">
+        <title>
+            Markdown
+        <paragraph>
+            <reference refuri="http://example.com/">
+                target
         <target refid="inc-header">
         <section ids="a-sub-heading-in-include inc-header" names="a\ sub-heading\ in\ include inc_header">
             <title>