🐛 Accurate directive line mapping and source-attributed nested renders

[chrisjsewell]

Closes three directive-API fidelity gaps characterised while making sphinx-jinja2's warnings line-accurate (myst-parser 4.0.1/5.1.0, re-verified against master post-#1164).

content_offset is now document-relative (rST convention)

Directives run under MyST received content_offset = body_offset (directive-relative), so the conventional content_offset + N idiom reported lines near the top of the file wherever the fence sat. Directives now receive the 0-based document line of their first content line, and self.content.items carry per-line absolute lines — both exactly what docutils' rST parser provides. Coupled with this, MockState.nested_parse treats input_offset as an absolute document offset. For the standard nested_parse(self.content, self.content_offset, node) idiom the rendered position is unchanged (the two old offsets summed to the same number), so no rendering fixture changes; the external contract is what's fixed.

Free corrections that fell out: {epigraph} attribution .line (was one too small), {parsed-literal} .line (was hardcoded 1), and myst's own _docs.py directives.

Source-attributed nested renders (supported API)

DocutilsRenderer.nested_render_text(text, lineno, source=...) attributes rendered nodes and warnings (sphinx logger + docutils reporter, symmetrically) to a caller-specified path, exception-safe and re-entrant. Since #1114 switched warning locations to env.docname, the document/reporter override dance was inert under sphinx — {include} itself was affected: warnings inside included markdown were logged against the including document, one line off. Includes now cite the included file at the true line (the #1164 "tracked separately" off-by-one), and :start-after: no longer derives line numbers from a character index (previously past-EOF lines like inc.md:19 in a 5-line file).

Supported insertion API

• MockStateMachine.insert_input(input_lines, source=None) — docutils-compatible signature; parsed as MyST (documented caveat), rendered at the directive's position, attributed to source:1..n.
• MockState.renderer / MockStateMachine.renderer properties bless the access path.
• New docs/develop/extending.md documents the API with an explicit stability promise, lineno line-space semantics, eval-rst semantics (already document-absolute; now pinned by test), and limitations (deferred document-level warnings; inline tokens).

Behaviour notes for extension authors (also in changelog)

• nested_parse with literal relative offsets (e.g. autodoc/autosummary's offset=0) now places content at the document top, as under rST.
• self.lineno + self.content_offset arithmetic now double-counts — as it always did under rST (sphinx-design's badges/buttons hit this latent pattern).
• Duplicate-reference-definition warnings still attribute to the containing document (deferred post-parse; documented limitation).

Verification

• 1245 → 1285 passed, 11 skipped; ruff/format/mypy clean; docs build clean.
• The originating scenario end-to-end: a fence at line 9 mapping an error on content line 2 via content_offset + 2 now warns at index.md:11 (was index.md:3).
• Master-vs-branch doctrees byte-identical on real docs; only warning-location outputs changed, each hand-verified against true source lines; parse-time delta within noise.
• Adversarially reviewed in two rounds (edge-case probes incl. nested/list/blockquote/eval-rst fences, include chains and slicing options, mutation testing of the new tests, downstream sweep: myst-nb unaffected, sphinx-design standard idioms invariant).

Downstream (sphinx-jinja2): the isinstance(state_machine, StateMachine) gate can become a version check, the override dance collapses onto nested_render_text(..., source=template_path), and its test_myst_render_error_location can assert line-accurate expectations.