myst_parser.sphinx_ext.myst_refs#

A post-transform for overriding the behaviour of sphinx reference resolution.

This is applied to MyST type references only, such as [text](target), and allows for nested syntax

1.  Module Contents#

1.1.  Classes#

MystReferenceResolver

Resolves cross-references on doctrees.

1.2.  Data#

LOGGER

1.3.  API#

myst_parser.sphinx_ext.myst_refs.LOGGER = None#
class myst_parser.sphinx_ext.myst_refs.MystReferenceResolver(document, startnode=None)[source]#

Bases: sphinx.transforms.post_transforms.ReferencesResolver

Resolves cross-references on doctrees.

Overrides default sphinx implementation, to allow for nested syntax

Initialization

Initial setup for in-place document transforms.

default_priority = 9#
log_warning(target: None | str, msg: str, subtype: myst_parser.warnings_.MystWarnings, **kwargs: Any)[source]#

Log a warning, with a myst type and specific subtype.

run(**kwargs: Any) → None[source]#
resolve_myst_ref_doc(node: sphinx.addnodes.pending_xref)[source]#

Resolve a reference, from a markdown link, to another document, optionally with a target id within that document.

resolve_myst_ref_any(refdoc: str, node: sphinx.addnodes.pending_xref, contnode: docutils.nodes.Element, only_domains: None | list[str]) → docutils.nodes.Element | None[source]#

Resolve reference generated by the “myst” role; [text](#reference).

This builds on the sphinx any role to also resolve:

  • Document references with extensions; [text](./doc.md)

  • Document references with anchors with anchors; [text](./doc.md#target)

  • Nested syntax for explicit text with std:doc and std:ref; [**nested**](reference)