How do cross-references work?

[Max Rothman]

Hi all,

I'm looking for some help in poking at the Sphinx/Docutils internals. How do cross-references work in Sphinx and Docutils on the API level? It seems like they may be related to the names property of nodes in  docutils.transforms.references, but docutils.nodes.note_explicit_index seems to use ids. Does Sphinx use that same system to resolve cross-references across multiple documents? If names isn't used for xrefs, what does it do?

Thanks,
Max

[Komiya Takeshi]

Hi,

Sphinx provides domain system to resolve cross reference across the files.

It is based on concept of docutils, but it is original feature of Sphinx.

The domain system supports collecting reference targets from whole of document and resolving the references.

Sorry, I have no time to describe about the domains now.

Please refer the document (http://www.sphinx-doc.org/en/stable/domains.html) and source code.

Thanks,

Takeshi KOMIYA

2016年4月20日水曜日 1時08分45秒 UTC+9 Max Rothman:

[Max Rothman]

Is the domain system what actually resolves the xrefs? If so, how does :ref: work, and why do all domain ObjectDescription subclasses call docutils.nodes.note_explicit_index? 

Thanks,

Max

[Max Rothman]

Sorry, that's note_explicit_target(), not note_explicit_index()