Extension internals

References between distinct PDF documents

Sphinx references point to the source file of their targets. That matches the HTML builder well, because generally one source file turns into one HTML output file. However, the LaTeX builder generally puts multiple source files into a single output file.

  1. Collect latex_document nodes: iterate over all source files and traverse their doctrees.
  2. Assemble doctrees of latex_document nodes: use Sphinx’ built-in assembling logic.
  3. Determine which source files went into which latex_document nodes: traverse the doctree of each latex_document node looking for start_of_file nodes.

Resolving of references

System Message: ERROR/3 (/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-multilatex/checkouts/latest/docs/internals.txt, line 24)

Unknown directive type “uml”.

.. uml::

    LaTeXBuilder -> LaTeXBuilder: assemble_doctree
    LaTeXBuilder -> BuildEnvironment: resolve_references
    BuildEnvironment -> StandardDomain: resolve_xref
    StandardDomain -> StandardDomain: build_reference_node
    StandardDomain -> LaTeXBuilder: get_relative_uri
    LaTeXBuilder -> LaTeXBuilder: get_target_uri
    alt Sphinx' builtin LaTeXBuilder
        LaTeXBuilder -> LaTeXBuilder: Check that reference\nis in current LaTeX\noutput document
        LaTeXBuilder ->]: raise NoUri
    else This extension
        LaTeXBuilder --> StandardDomain: Inter-document URI string\nfor reference node
    end

Resolving of references

System Message: ERROR/3 (/home/docs/checkouts/readthedocs.org/user_builds/sphinxcontrib-multilatex/checkouts/latest/docs/internals.txt, line 42)

Unknown directive type “uml”.

.. uml::

    LaTeXWriter -> document: walkabout
    ... Traverse document tree ...
    document -> LaTeXTranslator: visit_reference
    ... Traverse document tree ...