Aligns directive's block_text content to rST's

[kdeldycke]

In rST, a directive's block_text contains the entire directive, including options and full, unparsed content.

This aligns MyST parser to rST.

Context

I stumbled upon this issue while implementing my own click:example and click:run directives within my Click Extra project: https://kdeldycke.github.io/click-extra/sphinx.html

My implementation is trying to report, within these directives, of the absolute line in the document where a problem occured. The line number and offset calculation works perfectly in rST, but requires some hacks to report the right one in MyST.

But even with these hacks, there is no way to retro-actively compute the absolute line number, because the directive object do not carry its unparsed content.

Example

Compare a given rST directive defined as:

 .. click:run::
    :linenos:

    # This should fail due to variable conflict.
    isolated_filesystem = "Do not overwrite me!"

Its properties are:

>>> print("\n".join(directive.content))
# This should fail due to variable conflict.
isolated_filesystem = "Do not overwrite me!"

>>> print(directive.block_text)
.. click:run::
    :linenos:

    # This should fail due to variable conflict.
    isolated_filesystem = "Do not overwrite me!"

And for its MyST equivalent:

```{click:run}
:linenos:
# This should fail due to variable conflict.
isolated_filesystem = "Do not overwrite me!"
```

>>> print("\n".join(directive.content))
# This should fail due to variable conflict.
isolated_filesystem = "Do not overwrite me!"

>>> print(directive.block_text)
# This should fail due to variable conflict.
isolated_filesystem = "Do not overwrite me!"

Limitations

Note that it is not perfect, as it is supposed to also contain:

• the complete directive header (i.e the ```{name} {arguments} first line), and
• the directive closing line (i.e. the ``` line).

But I doubt we can find a way to do it unless we introduce heavier refactor.

[chrisjsewell]

Thanks for this @kdeldycke, and apologies it sat unreviewed for so long.

#1164 now supersedes this: rather than passing the unparsed content only, it reconstructs the full directive text from the fence token — including the opening ```{name} args line and the closing fence that this PR noted it could not include — so block_text should now give you exactly the rST-parity line arithmetic you were after in click-extra, without the workarounds. There's a covering test pinning the reconstructed form.

I'll close this once #1164 is merged.

---

Generated by Claude Code