Sphinx

# Source code for sphinx.builders.latex

    """LaTeX builder."""

    from __future__ import annotations

    import os
    import os.path
    from pathlib import Path
    from typing import TYPE_CHECKING

    import sphinx.builders.latex.nodes  # NoQA: F401  # Workaround: import this before writer to avoid ImportError
    from sphinx import addnodes, highlighting, package_dir
    from sphinx._cli.util.colour import darkgreen
    from sphinx.builders import Builder
    from sphinx.builders.latex.constants import (
        ADDITIONAL_SETTINGS,
        DEFAULT_SETTINGS,
        SHORTHANDOFF,
    )
    from sphinx.builders.latex.theming import Theme, ThemeFactory
    from sphinx.builders.latex.util import ExtBabel
    from sphinx.config import ENUM
    from sphinx.environment.adapters.asset import ImageAdapter
    from sphinx.errors import NoUri, SphinxError
    from sphinx.locale import _, __
    from sphinx.util import logging, texescape
    from sphinx.util.display import progress_message, status_iterator
    from sphinx.util.docutils import _get_settings, new_document
    from sphinx.util.fileutil import copy_asset_file
    from sphinx.util.i18n import format_date
    from sphinx.util.nodes import inline_all_toctrees
    from sphinx.util.osutil import SEP, copyfile, make_filename_from_project
    from sphinx.util.template import LaTeXRenderer
    from sphinx.writers.latex import LaTeXTranslator, LaTeXWriter

    # load docutils.nodes after loading sphinx.builders.latex.nodes
    from docutils import nodes  # isort:skip

    if TYPE_CHECKING:
        from collections.abc import Iterable, Set
        from typing import Any

        from docutils.nodes import Node

        from sphinx.application import Sphinx
        from sphinx.config import Config
        from sphinx.util.typing import ExtensionMetadata

    XINDY_LANG_OPTIONS = {
        # language codes from docutils.writers.latex2e.Babel
        # ! xindy language names may differ from those in use by LaTeX/babel
        # ! xindy does not support all Latin scripts as recognized by LaTeX/babel
        # ! not all xindy-supported languages appear in Babel.language_codes
        # cd /usr/local/texlive/2018/texmf-dist/xindy/modules/lang
        # find . -name '*utf8.xdy'
        # LATIN
        'sq': '-L albanian -C utf8 ',
        'hr': '-L croatian -C utf8 ',
        'cs': '-L czech -C utf8 ',
        'da': '-L danish -C utf8 ',
        'nl': '-L dutch-ij-as-ij -C utf8 ',
        'en': '-L english -C utf8 ',
        'eo': '-L esperanto -C utf8 ',
        'et': '-L estonian -C utf8 ',
        'fi': '-L finnish -C utf8 ',
        'fr': '-L french -C utf8 ',
        'de': '-L german-din5007 -C utf8 ',
        'is': '-L icelandic -C utf8 ',
        'it': '-L italian -C utf8 ',
        'la': '-L latin -C utf8 ',
        'lv': '-L latvian -C utf8 ',
        'lt': '-L lithuanian -C utf8 ',
        'dsb': '-L lower-sorbian -C utf8 ',
        'ds': '-L lower-sorbian -C utf8 ',   # trick, no conflict
        'nb': '-L norwegian -C utf8 ',
        'no': '-L norwegian -C utf8 ',       # and what about nynorsk?
        'pl': '-L polish -C utf8 ',
        'pt': '-L portuguese -C utf8 ',
        'ro': '-L romanian -C utf8 ',
        'sk': '-L slovak-small -C utf8 ',    # there is also slovak-large
        'sl': '-L slovenian -C utf8 ',
        'es': '-L spanish-modern -C utf8 ',  # there is also spanish-traditional
        'sv': '-L swedish -C utf8 ',
        'tr': '-L turkish -C utf8 ',
        'hsb': '-L upper-sorbian -C utf8 ',
        'hs': '-L upper-sorbian -C utf8 ',   # trick, no conflict
        'vi': '-L vietnamese -C utf8 ',
        # CYRILLIC
        # for usage with pdflatex, needs also cyrLICRutf8.xdy module
        'be': '-L belarusian -C utf8 ',
        'bg': '-L bulgarian -C utf8 ',
        'mk': '-L macedonian -C utf8 ',
        'mn': '-L mongolian-cyrillic -C utf8 ',
        'ru': '-L russian -C utf8 ',
        'sr': '-L serbian -C utf8 ',
        'sh-cyrl': '-L serbian -C utf8 ',
        'sh': '-L serbian -C utf8 ',         # trick, no conflict
        'uk': '-L ukrainian -C utf8 ',
        # GREEK
        # can work only with xelatex/lualatex, not supported by texindy+pdflatex
        'el': '-L greek -C utf8 ',
        # FIXME, not compatible with [:2] slice but does Sphinx support Greek ?
        'el-polyton': '-L greek-polytonic -C utf8 ',
    }  # fmt: skip

    XINDY_CYRILLIC_SCRIPTS = frozenset({'be', 'bg', 'mk', 'mn', 'ru', 'sr', 'sh', 'uk'})

    logger = logging.getLogger(__name__)

    class LaTeXBuilder(Builder):
        """Builds LaTeX output to create PDF."""

        name = 'latex'
        format = 'latex'
        epilog = __('The LaTeX files are in %(outdir)s.')
        if os.name == 'posix':
            epilog += __(
                "\nRun 'make' in that directory to run these through "
                '(pdf)latex\n'
                "(use `make latexpdf' here to do that automatically)."
            )

        supported_image_types = ['application/pdf', 'image/png', 'image/jpeg']
        supported_remote_images = False
        default_translator_class = LaTeXTranslator

        def init(self) -> None:
            self.babel: ExtBabel
            self.context: dict[str, Any] = {}
            self.docnames: Iterable[str] = {}
            self.document_data: list[tuple[str, str, str, str, str, bool]] = []
            self.themes = ThemeFactory(srcdir=self.srcdir, config=self.config)
            texescape.init()

            self.init_context()
            self.init_babel()
            self.init_multilingual()

        def get_outdated_docs(self) -> str | list[str]:
            return 'all documents'  # for now

        def get_target_uri(self, docname: str, typ: str | None = None) -> str:
            if docname not in self.docnames:
                raise NoUri(docname, typ)
            return '%' + docname

        def get_relative_uri(self, from_: str, to: str, typ: str | None = None) -> str:
            # ignore source path
            return self.get_target_uri(to, typ)

        def init_document_data(self) -> None:
            preliminary_document_data = [list(x) for x in self.config.latex_documents]
            if not preliminary_document_data:
                logger.warning(
                    __(
                        'no "latex_documents" config value found; no documents '
                        'will be written'
                    )
                )
                return
            # assign subdirs to titles
            self.titles: list[tuple[str, str]] = []
            for entry in preliminary_document_data:
                docname = entry[0]
                if docname not in self.env.all_docs:
                    logger.warning(
                        __('"latex_documents" config value references unknown document %s'),
                        docname,
                    )
                    continue
                self.document_data.append(entry)  # type: ignore[arg-type]
                docname = docname.removesuffix(SEP + 'index')
                self.titles.append((docname, entry[2]))

        def init_context(self) -> None:
            self.context = DEFAULT_SETTINGS.copy()

            # Add special settings for latex_engine
            self.context.update(ADDITIONAL_SETTINGS.get(self.config.latex_engine, {}))

            # Add special settings for (latex_engine, language_code)
            key = (self.config.latex_engine, self.config.language[:2])
            self.context.update(ADDITIONAL_SETTINGS.get(key, {}))

            # Apply user settings to context
            self.context.update(self.config.latex_elements)
            self.context['release'] = self.config.release
            self.context['use_xindy'] = self.config.latex_use_xindy
            self.context['booktabs'] = 'booktabs' in self.config.latex_table_style
            self.context['borderless'] = 'borderless' in self.config.latex_table_style
            self.context['colorrows'] = 'colorrows' in self.config.latex_table_style

            if self.config.today:
                self.context['date'] = self.config.today
            else:
                today_fmt = self.config.today_fmt or _('%b %d, %Y')
                self.context['date'] = format_date(today_fmt, language=self.config.language)

            if self.config.latex_logo:
                self.context['logofilename'] = os.path.basename(self.config.latex_logo)

            # for compatibilities
            self.context['indexname'] = _('Index')
            if self.config.release:
                # Show the release label only if release value exists
                self.context.setdefault('releasename', _('Release'))

        def update_context(self) -> None:
            """Update template variables for .tex file just before writing."""
            # Apply extension settings to context
            registry = self._registry
            self.context['packages'] = registry.latex_packages
            self.context['packages_after_hyperref'] = registry.latex_packages_after_hyperref

        def init_babel(self) -> None:
            self.babel = ExtBabel(self.config.language, not self.context['babel'])
            if not self.babel.is_supported_language():
                # emit warning if specified language is invalid
                # (only emitting, nothing changed to processing)
                logger.warning(
                    __('no Babel option known for language %r'), self.config.language
                )

        def init_multilingual(self) -> None:
            if self.context['latex_engine'] == 'pdflatex':
                if not self.babel.uses_cyrillic():
                    if 'X2' in self.context['fontenc']:
                        self.context['substitutefont'] = (
                            '\\usepackage{sphinxpackagesubstitutefont}'
                        )
                        self.context['textcyrillic'] = (
                            '\\usepackage[Xtwo]{sphinxpackagecyrillic}'
                        )
                    elif 'T2A' in self.context['fontenc']:
                        self.context['substitutefont'] = (
                            '\\usepackage{sphinxpackagesubstitutefont}'
                        )
                        self.context['textcyrillic'] = (
                            '\\usepackage[TtwoA]{sphinxpackagecyrillic}'
                        )
                if 'LGR' in self.context['fontenc']:
                    self.context['substitutefont'] = (
                        '\\usepackage{sphinxpackagesubstitutefont}'
                    )
                else:
                    self.context['textgreek'] = ''
                if not self.context['substitutefont']:
                    self.context['fontsubstitution'] = ''

            # 'babel' key is public and user setting must be obeyed
            if self.context['babel']:
                self.context['classoptions'] += ',' + self.babel.get_language()
                # this branch is not taken for xelatex/lualatex if default settings
                self.context['multilingual'] = self.context['babel']
                self.context['shorthandoff'] = SHORTHANDOFF

                # Times fonts don't work with Cyrillic languages
                if (
                    self.babel.uses_cyrillic()
                    and 'fontpkg' not in self.config.latex_elements
                ):
                    self.context['fontpkg'] = ''
            elif self.context['polyglossia']:
                self.context['classoptions'] += ',' + self.babel.get_language()
                options = self.babel.get_mainlanguage_options()
                if options:
                    language = (
                        rf'\setmainlanguage[{options}]{{{self.babel.get_language()}}}'
                    )
                else:
                    language = r'\setmainlanguage{%s}' % self.babel.get_language()

                self.context['multilingual'] = f'{self.context["polyglossia"]}\n{language}'

        def write_stylesheet(self) -> None:
            highlighter = highlighting.PygmentsBridge('latex', self.config.pygments_style)
            stylesheet = self.outdir / 'sphinxhighlight.sty'
            with open(stylesheet, 'w', encoding='utf-8') as f:
                f.write('\\NeedsTeXFormat{LaTeX2e}[1995/12/01]\n')
                f.write(
                    '\\ProvidesPackage{sphinxhighlight}'
                    '[2022/06/30 stylesheet for highlighting with pygments]\n'
                )
                f.write(
                    '% Its contents depend on pygments_style configuration variable.\n\n'
                )
                f.write(highlighter.get_stylesheet())

        def prepare_writing(self, docnames: Set[str]) -> None:
            self.init_document_data()
            self.write_stylesheet()

        def copy_assets(self) -> None:
            self.copy_support_files()

            if self.config.latex_additional_files:
                self.copy_latex_additional_files()

        def write_documents(self, _docnames: Set[str]) -> None:
            docsettings = _get_settings(
                LaTeXWriter, defaults=self.env.settings, read_config_files=True
            )

            for entry in self.document_data:
                docname, targetname, title, author, themename = entry[:5]
                theme = self.themes.get(themename)
                toctree_only = False
                if len(entry) > 5:
                    toctree_only = entry[5]
                with progress_message(__('processing %s') % targetname, nonl=False):
                    doctree = self.env.get_doctree(docname)
                    toctree = next(doctree.findall(addnodes.toctree), None)
                    if toctree and toctree.get('maxdepth') > 0:
                        tocdepth = toctree.get('maxdepth')
                    else:
                        tocdepth = None

                    doctree = self.assemble_doctree(
                        docname,
                        toctree_only,
                        appendices=(
                            self.config.latex_appendices if theme.name != 'howto' else []
                        ),
                    )
                    doctree['docclass'] = theme.docclass
                    doctree['contentsname'] = self.get_contentsname(docname)
                    doctree['tocdepth'] = tocdepth
                    self.post_process_images(doctree)
                    self.update_doc_context(title, author, theme)
                    self.update_context()

                with progress_message(__('writing')):
                    docsettings._author = author
                    docsettings._title = title
                    docsettings._contentsname = doctree['contentsname']
                    docsettings._docname = docname
                    docsettings._docclass = theme.name

                    doctree.settings = docsettings
                    visitor: LaTeXTranslator = self.create_translator(doctree, self, theme)  # type: ignore[assignment]
                    doctree.walkabout(visitor)
                    output = visitor.astext()
                    destination_path = self.outdir / targetname
                    # https://github.com/sphinx-doc/sphinx/issues/4362
                    if (
                        not destination_path.is_file()
                        or destination_path.read_bytes() != output.encode()
                    ):
                        destination_path.write_text(output, encoding='utf-8')

        def get_contentsname(self, indexfile: str) -> str:
            tree = self.env.get_doctree(indexfile)
            contentsname = ''
            for toctree in tree.findall(addnodes.toctree):
                if 'caption' in toctree:
                    contentsname = toctree['caption']
                    break

            return contentsname

        def update_doc_context(self, title: str, author: str, theme: Theme) -> None:
            self.context['title'] = title
            self.context['author'] = author
            self.context['docclass'] = theme.docclass
            self.context['papersize'] = theme.papersize
            self.context['pointsize'] = theme.pointsize
            self.context['wrapperclass'] = theme.wrapperclass

        def assemble_doctree(
            self,
            indexfile: str,
            toctree_only: bool,
            appendices: list[str],
        ) -> nodes.document:
            self.docnames = {indexfile, *appendices}
            logger.info(darkgreen(indexfile))
            tree = self.env.get_doctree(indexfile)
            tree['docname'] = indexfile
            if toctree_only:
                # extract toctree nodes from the tree and put them in a
                # fresh document
                new_tree = new_document('<latex output>')
                new_sect = nodes.section()
                new_sect += nodes.title('<Set title in conf.py>', '<Set title in conf.py>')
                new_tree += new_sect
                for node in tree.findall(addnodes.toctree):
                    new_sect += node
                tree = new_tree
            largetree = inline_all_toctrees(
                self, self.docnames, indexfile, tree, darkgreen, [indexfile]
            )
            largetree['docname'] = indexfile
            for docname in appendices:
                appendix = self.env.get_doctree(docname)
                appendix['docname'] = docname
                largetree.append(appendix)
            logger.info('')
            logger.info(__('resolving references...'))
            self.env.resolve_references(largetree, indexfile, self)
            # resolve :ref:s to distant tex files -- we can't add a cross-reference,
            # but append the document name
            for pendingnode in largetree.findall(addnodes.pending_xref):
                docname = pendingnode['refdocname']
                sectname = pendingnode['refsectname']
                newnodes: list[Node] = [nodes.emphasis(sectname, sectname)]
                for subdir, title in self.titles:
                    if docname.startswith(subdir):
                        newnodes.extend((
                            nodes.Text(_(' (in ')),
                            nodes.emphasis(title, title),
                            nodes.Text(')'),
                        ))
                        break
                pendingnode.replace_self(newnodes)
            return largetree

        def finish(self) -> None:
            self.copy_image_files()
            self.write_message_catalog()

        @progress_message(__('copying TeX support files'))
        def copy_support_files(self) -> None:
            """Copy TeX support files from texinputs."""
            # configure usage of xindy (impacts Makefile and latexmkrc)
            # FIXME: convert this rather to a confval with suitable default
            #        according to language ? but would require extra documentation
            xindy_lang_option = XINDY_LANG_OPTIONS.get(
                self.config.language[:2], '-L general -C utf8 '
            )
            xindy_cyrillic = self.config.language[:2] in XINDY_CYRILLIC_SCRIPTS

            context = {
                'latex_engine': self.config.latex_engine,
                'xindy_use': self.config.latex_use_xindy,
                'xindy_lang_option': xindy_lang_option,
                'xindy_cyrillic': xindy_cyrillic,
            }
            static_dir_name = package_dir / 'texinputs'
            for filename in Path(static_dir_name).iterdir():
                if not filename.name.startswith('.'):
                    copy_asset_file(
                        static_dir_name / filename,
                        self.outdir,
                        context=context,
                        force=True,
                    )

            # use pre-1.6.x Makefile for make latexpdf on Windows
            if os.name == 'nt':
                static_dir_name = package_dir / 'texinputs_win'
                copy_asset_file(
                    static_dir_name / 'Makefile.jinja',
                    self.outdir,
                    context=context,
                    force=True,
                )

        @progress_message(__('copying additional files'))
        def copy_latex_additional_files(self) -> None:
            for filename in self.config.latex_additional_files:
                logger.info(' %s', filename, nonl=True)
                source = self.confdir / filename
                copyfile(
                    source,
                    self.outdir / source.name,
                    force=True,
                )

        def copy_image_files(self) -> None:
            if self.images:
                stringify_func = ImageAdapter(self.env).get_original_image_uri
                for src in status_iterator(
                    self.images,
                    __('copying images... '),
                    'brown',
                    len(self.images),
                    self.config.verbosity,
                    stringify_func=stringify_func,
                ):
                    dest = self.images[src]
                    try:
                        copyfile(
                            self.srcdir / src,
                            self.outdir / dest,
                            force=True,
                        )
                    except Exception as err:
                        logger.warning(
                            __('cannot copy image file %r: %s'),
                            self.srcdir / src,
                            err,
                        )
            if self.config.latex_logo:
                source = self.confdir / self.config.latex_logo
                if not source.is_file():
                    raise SphinxError(
                        __('logo file %r does not exist') % self.config.latex_logo
                    )
                copyfile(
                    source,
                    self.outdir / source.name,
                    force=True,
                )

        def write_message_catalog(self) -> None:
            formats = self.config.numfig_format
            context = {
                'addtocaptions': r'\@iden',
                'figurename': formats.get('figure', '').split('%s', maxsplit=1),
                'tablename': formats.get('table', '').split('%s', maxsplit=1),
                'literalblockname': formats.get('code-block', '').split('%s', maxsplit=1),
            }

            if self.context['babel'] or self.context['polyglossia']:
                context['addtocaptions'] = r'\addto\captions%s' % self.babel.get_language()

            copy_asset_file(
                package_dir.joinpath('templates', 'latex', 'sphinxmessages.sty.jinja'),
                self.outdir,
                context=context,
                renderer=LaTeXRenderer(),
                force=True,
            )

    def validate_config_values(app: Sphinx, config: Config) -> None:
        for key in list(config.latex_elements):
            if key not in DEFAULT_SETTINGS:
                msg = __('Unknown configure key: latex_elements[%r], ignored.')
                logger.warning(msg, key)
                config.latex_elements.pop(key)

    def validate_latex_theme_options(app: Sphinx, config: Config) -> None:
        for key in list(config.latex_theme_options):
            if key not in Theme.UPDATABLE_KEYS:
                msg = __('Unknown theme option: latex_theme_options[%r], ignored.')
                logger.warning(msg, key)
                config.latex_theme_options.pop(key)

    def install_packages_for_ja(app: Sphinx) -> None:
        """Install packages for Japanese."""
        if app.config.language == 'ja' and app.config.latex_engine in {'platex', 'uplatex'}:
            app.add_latex_package('pxjahyper', after_hyperref=True)

    def default_latex_engine(config: Config) -> str:
        """Better default latex_engine settings for specific languages."""
        if config.language == 'ja':
            return 'uplatex'
        if config.language.startswith('zh'):
            return 'xelatex'
        if config.language == 'el':
            return 'xelatex'
        return 'pdflatex'

    def default_latex_docclass(config: Config) -> dict[str, str]:
        """Better default latex_docclass settings for specific languages."""
        if config.language == 'ja':
            if config.latex_engine == 'uplatex':
                return {'manual': 'ujbook', 'howto': 'ujreport'}
            else:
                return {'manual': 'jsbook', 'howto': 'jreport'}
        else:
            return {}

    def default_latex_use_xindy(config: Config) -> bool:
        """Better default latex_use_xindy settings for specific engines."""
        return config.latex_engine in {'xelatex', 'lualatex'}

    def default_latex_documents(config: Config) -> list[tuple[str, str, str, str, str]]:
        """Better default latex_documents settings."""
        project = texescape.escape(config.project, config.latex_engine)
        author = texescape.escape(config.author, config.latex_engine)
        return [
            (
                config.root_doc,
                make_filename_from_project(config.project) + '.tex',
                texescape.escape_abbr(project),
                texescape.escape_abbr(author),
                config.latex_theme,
            )
        ]

    def setup(app: Sphinx) -> ExtensionMetadata:
        app.setup_extension('sphinx.builders.latex.transforms')

        app.add_builder(LaTeXBuilder)
        app.connect('config-inited', validate_config_values, priority=800)
        app.connect('config-inited', validate_latex_theme_options, priority=800)
        app.connect('builder-inited', install_packages_for_ja)

        app.add_config_value(
            'latex_engine',
            default_latex_engine,
            '',
            types=ENUM('pdflatex', 'xelatex', 'lualatex', 'platex', 'uplatex'),
        )
        app.add_config_value(
            'latex_documents', default_latex_documents, '', types=frozenset({list, tuple})
        )
        app.add_config_value('latex_logo', None, '', types=frozenset({str}))
        app.add_config_value('latex_appendices', [], '', types=frozenset({list, tuple}))
        app.add_config_value(
            'latex_use_latex_multicolumn', False, '', types=frozenset({bool})
        )
        app.add_config_value(
            'latex_use_xindy', default_latex_use_xindy, '', types=frozenset({bool})
        )
        app.add_config_value(
            'latex_toplevel_sectioning',
            None,
            '',
            types=ENUM(None, 'part', 'chapter', 'section'),
        )
        app.add_config_value(
            'latex_domain_indices', True, '', types=frozenset({frozenset, list, set, tuple})
        )
        app.add_config_value('latex_show_urls', 'no', '', types=frozenset({str}))
        app.add_config_value('latex_show_pagerefs', False, '', types=frozenset({bool}))
        app.add_config_value('latex_elements', {}, '', types=frozenset({dict}))
        app.add_config_value(
            'latex_additional_files', [], '', types=frozenset({list, tuple})
        )
        app.add_config_value(
            'latex_table_style', ['booktabs', 'colorrows'], '', types=frozenset({list})
        )
        app.add_config_value('latex_theme', 'manual', '', types=frozenset({str}))
        app.add_config_value('latex_theme_options', {}, '', types=frozenset({dict}))
        app.add_config_value('latex_theme_path', [], '', types=frozenset({list}))

        app.add_config_value(
            'latex_docclass', default_latex_docclass, '', types=frozenset({dict})
        )

        return {
            'version': 'builtin',
            'parallel_read_safe': True,
            'parallel_write_safe': True,
        }