[saimskywalker]

Part of #202

This handles the case from the original issue: a numbered amsmath environment with a single \label{name} can now be referenced with {eq}`name`.

\begin{equation}
e^{i\pi} + 1 = 0 \label{eq:euler}
\end{equation}

The equation {eq}`eq:euler` is Euler's identity.

What changed

• The amsmath renderer looks for \label{...} in the environment content, ignoring % comments (but not \%). If it finds exactly one, that label is used for the math_block instead of the random uuid. It goes through the same add_math_target path as $$...$$ (label), so it is registered with the math domain, numbered, and gets an equation-<label> id. Duplicate labels give the usual ref.equation warning. Labels with colons work.
• The \label is left in the content, as before, so the rendered math in HTML doesn't change. Only the id and the equation number become referenceable.
• Whole environments are numbered as one equation, so only one label per environment is supported. If there is more than one, a new myst.math_label warning is emitted, none of the labels are used, and the environment is still numbered as before. Labels in starred environments are ignored.
• LaTeX output: for nowrap math, Sphinx writes \label{equation:doc:label} before the content, so \eqref would point at the section counter, not the environment. A small math_block LaTeX visitor override handles amsmath blocks whose label comes from the content: it renames the \label inside the environment to equation:doc:label, so \eqref gets the right number. Every other math block goes to the translator's normal visit_math_block.
• Docutils renderer: the label is added as a name on the math_block, the same way $$...$$ (label) is handled there, so [](#name) links work.
• Docs: replaced the "labels are not identified" note in optional.md, and added an example to math.md.

What's not covered

Per-line labels in multi-line environments like align, e.g. a &= 1 \label{eq1} \\ b &= 2 \label{eq2}. Sphinx's math domain gives one number per math_block, so this would need per-line numbering in HTML and a different AST representation, which is the larger design question you raised in the issue. This PR warns on that case and does not try to guess.

Tests

• tests/test_renderers/fixtures/amsmath.md: single label, label plus {eq} reference, label in a comment, label after \%, starred environment, multiple labels with the warning. test_amsmath now also checks warnings, like test_link_resolution does.
• docutil_syntax_extensions.txt: label as a name, [link](#eq:a) resolution, and the multiple-label warning.
• extended_syntaxes build: HTML now has <a href="#equation-eq-labelled">(3)</a>, and a new LaTeX build test checks c=4 \label{equation:index:eq:labelled} and \eqref{equation:index:eq:labelled}.
• The new tests fail on master and pass on this branch. I ran the full suite on Python 3.14 / Sphinx 9.2 / docutils 0.23 and on Python 3.11 / Sphinx 8.2 / docutils 0.21. ruff and mypy are clean, and sphinx-build -nW on the docs passes.
• I couldn't compile the LaTeX locally (no TeX install here). I checked the generated .tex by hand.