Skip to content

🐛 FIX: Point nested {eval-rst} nodes at the real document - #1242

Open
tony1233200 wants to merge 1 commit into
executablebooks:masterfrom
tony1233200:fix/1241-eval-rst-document
Open

tony1233200 wants to merge 1 commit into
executablebooks:masterfrom
tony1233200:fix/1241-eval-rst-document

Conversation

@tony1233200

Copy link
Copy Markdown

Fixes #1241.

Problem

{eval-rst} blocks leave nested nodes pointing at a temporary document, so every pickled doctree that contains such a block also embeds the Sphinx BuildEnvironment. The cost grows with the size of the environment, for every page that uses {eval-rst}.

Root cause

DocutilsRenderer.render_restructuredtext parses the block into a temporary document (newdoc) that shares the page's settings, then merges its children with Element.extend. extend -> setup_child only sets .document on the direct children, so every deeper node (for example the contents of a nested bullet list) keeps .document set to newdoc.

Sphinx's write_doctree sets env = None on its own copy of the document settings before pickling, but newdoc.settings is the original shared object, which still has env. Pickling a stray node follows node.document -> newdoc -> settings.env.

Fix

After merging, walk the merged children and point every descendant element at the real document (3 lines in myst_parser/mdit_to_docutils/base.py).

Evidence

Regression test tests/test_docutils.py::test_eval_rst_nested_nodes_belong_to_document (an {eval-rst} block with a nested bullet list, asserting every element's .document is the real document):

  • Before the fix: fails (6 elements still point at the temporary document).
  • After the fix: passes.

Real Sphinx build of a one-page project with the same block, size of the pickled index.doctree:

  • Before: 18,803 bytes, contains BuildEnvironment.
  • After: 3,483 bytes, no BuildEnvironment.

Suite and checks (Python 3.12, Sphinx 9.1.1, docutils 0.22.4, linkify-it-py installed):

  • pytest tests: 1566 passed, 11 skipped. (Without linkify-it-py, 3 linkify tests fail identically on the unmodified code.)
  • pre-commit run --files <changed files>: ruff check, ruff format, mypy, end-of-file and trailing-whitespace all pass.

`render_restructuredtext` parses the block into a temporary document that
shares the page's settings, then merges its children with
`Element.extend`. That only sets `.document` on the direct children, so
every deeper node kept pointing at the temporary document.

Sphinx strips `settings.env` from its own copy of the settings before it
pickles a doctree, but not from the temporary document's settings, so a
stray node pulled the whole `BuildEnvironment` into the page's `.doctree`.

Re-parent all merged descendants to the real document.

Fixes executablebooks#1241

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

{eval-rst} blocks leave nodes pointing at a temporary document, so every pickled doctree embeds the Sphinx BuildEnvironment

1 participant