diff --git a/CHANGES.rst b/CHANGES.rst index 3f0ce6e7ba0..915f35c4014 100644 --- a/CHANGES.rst +++ b/CHANGES.rst @@ -12,6 +12,11 @@ Incompatible changes * #12763: Remove unused internal class ``sphinx.util.Tee``. Patch by Adam Turner. +* #12822: LaTeX: for Unicode engines, the :ref:`fvset` default is changed to + ``'\\fvset{fontsize=auto}'`` from ``'\\fvset{fontsize=\\small}'``. + Code-blokcs are unchanged as FreeMono is now loaded with ``Scale=0.9``. + An adjustement to existing projects is needed only if they used a custom + :ref:`fontpkg` configuration and did not set :ref:`fvset`. Deprecated ---------- @@ -78,11 +83,19 @@ Bugs fixed rise to nested ``\DUrole``'s, rather than a single one with comma separated classes. Patch by Jean-François B. +* #12831: LaTeX: avoid large voids sometimes occurring at page bottoms. + Patch by Jean-François B. * #11970, #12551: singlehtml builder: make target URIs to be same-document references in the sense of :rfc:`RFC 3986, §4.4 <3986#section-4.4>`, e.g., ``index.html#foo`` becomes ``#foo``. (note: continuation of a partial fix added in Sphinx 7.3.0) Patch by James Addison (with reference to prior work by Eric Norige) +* #12735: Fix :pep:`695` generic classes LaTeX output formatting. + Patch by Jean-François B. and Bénédikt Tran. +* #12782: intersphinx: fix double forward slashes when generating the inventory + file URL (user-defined base URL of an intersphinx project are left untouched + even if they end with double forward slashes). + Patch by Bénédikt Tran. Testing ------- diff --git a/doc/changes/3.5.rst b/doc/changes/3.5.rst index 6eea1092de0..4a060c0f251 100644 --- a/doc/changes/3.5.rst +++ b/doc/changes/3.5.rst @@ -108,7 +108,7 @@ Features added functions in source code and keep them not evaluated for readability. * #8619: html: kbd role generates customizable HTML tags for compound keys * #8634: html: Allow to change the order of JS/CSS via ``priority`` parameter - for :meth:`.Sphinx.add_js_file()` and :meth:`.Sphinx.add_css_file()` + for :meth:`.Sphinx.add_js_file` and :meth:`.Sphinx.add_css_file` * #6241: html: Allow to add JS/CSS files to the specific page when an extension calls ``app.add_js_file()`` or ``app.add_css_file()`` on :event:`html-page-context` event diff --git a/doc/changes/4.4.rst b/doc/changes/4.4.rst index 54692dacb2e..d6a60a370d9 100644 --- a/doc/changes/4.4.rst +++ b/doc/changes/4.4.rst @@ -27,7 +27,7 @@ Features added by an extlink, suggesting a replacement. * #9961: html: Support nested HTML elements in other HTML builders * #10013: html: Allow to change the loading method of JS via ``loading_method`` - parameter for :meth:`.Sphinx.add_js_file()` + parameter for :meth:`.Sphinx.add_js_file` * #9551: html search: "Hide Search Matches" link removes "highlight" parameter from URL * #9815: html theme: Wrap sidebar components in div to allow customizing their diff --git a/doc/conf.py b/doc/conf.py index aad73e59bca..2de3f34aa2e 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -4,8 +4,16 @@ import os import re import time +from typing import TYPE_CHECKING -from sphinx import __display_version__ +from sphinx import __display_version__, addnodes +from sphinx.application import Sphinx +from sphinx.environment import BuildEnvironment + +if TYPE_CHECKING: + from pathlib import Path + + from docutils import nodes os.environ['SPHINX_AUTODOC_RELOAD_MODULES'] = '1' @@ -254,13 +262,10 @@ # -- Extension interface ------------------------------------------------------- -from sphinx import addnodes # NoQA: E402 -from sphinx.application import Sphinx # NoQA: E402, TCH001 - _event_sig_re = re.compile(r'([a-zA-Z-]+)\s*\((.*)\)') -def parse_event(env, sig, signode): +def parse_event(_env: BuildEnvironment, sig: str, signode: nodes.Element) -> str: m = _event_sig_re.match(sig) if m is None: signode += addnodes.desc_name(sig, sig) @@ -275,11 +280,13 @@ def parse_event(env, sig, signode): return name -def linkify_issues_in_changelog(app, path, docname, source): +def linkify_issues_in_changelog( + _app: Sphinx, _path: Path, docname: str, source: list[str] +) -> None: """Linkify issue references like #123 in changelog to GitHub.""" if docname == 'changes': - def linkify(match): + def linkify(match: re.Match[str]) -> str: url = 'https://github.com/sphinx-doc/sphinx/issues/' + match[1] return f'`{match[0]} <{url}>`_' @@ -338,7 +345,7 @@ def setup(app: Sphinx) -> None: app.connect('include-read', linkify_issues_in_changelog) app.connect('build-finished', build_redirects) fdesc = GroupedField( - 'parameter', label='Parameters', names=['param'], can_collapse=True + 'parameter', label='Parameters', names=('param',), can_collapse=True ) app.add_object_type( 'event', diff --git a/doc/development/html_themes/index.rst b/doc/development/html_themes/index.rst index 18a345d3f71..3cfb40dc3a7 100644 --- a/doc/development/html_themes/index.rst +++ b/doc/development/html_themes/index.rst @@ -145,7 +145,7 @@ Python :mod:`configparser` module) and has the following structure: * The **pygments_dark_style** setting gives the name of a Pygments style to use for highlighting when the CSS media query ``(prefers-color-scheme: dark)`` evaluates to true. It is injected into the page using - :meth:`~sphinx.application.Sphinx.add_css_file()`. + :meth:`~sphinx.application.Sphinx.add_css_file`. * The **sidebars** setting gives the comma separated list of sidebar templates for constructing sidebars. This can be overridden by the user in the diff --git a/doc/extdev/deprecated.rst b/doc/extdev/deprecated.rst index 2a9cfb70601..1d2c60dc47d 100644 --- a/doc/extdev/deprecated.rst +++ b/doc/extdev/deprecated.rst @@ -1447,12 +1447,12 @@ The following is a list of deprecated interfaces. * - :meth:`!add_stylesheet` - 1.8 - 6.0 - - :meth:`~sphinx.application.Sphinx.add_css_file()` + - :meth:`~sphinx.application.Sphinx.add_css_file` - * - :meth:`!add_javascript()` + * - :meth:`!add_javascript` - 1.8 - 4.0 - - :meth:`~sphinx.application.Sphinx.add_js_file()` + - :meth:`~sphinx.application.Sphinx.add_js_file` * - :confval:`autodoc_default_flags` - 1.8 @@ -1519,7 +1519,7 @@ The following is a list of deprecated interfaces. * - ``sphinx.ext.mathbase.setup_math()`` - 1.8 - 3.0 - - :meth:`~sphinx.application.Sphinx.add_html_math_renderer()` + - :meth:`~sphinx.application.Sphinx.add_html_math_renderer` * - ``sphinx.ext.mathbase.is_in_section_title()`` - 1.8 @@ -1700,7 +1700,7 @@ The following is a list of deprecated interfaces. * - ``Sphinx.override_domain()`` - 1.8 - 3.0 - - :meth:`~sphinx.application.Sphinx.add_domain()` + - :meth:`~sphinx.application.Sphinx.add_domain` * - ``Sphinx.import_object()`` - 1.8 @@ -1708,10 +1708,10 @@ The following is a list of deprecated interfaces. - ``sphinx.util.import_object()`` * - ``suffix`` argument of - :meth:`~sphinx.application.Sphinx.add_source_parser()` + :meth:`~sphinx.application.Sphinx.add_source_parser` - 1.8 - 3.0 - - :meth:`~sphinx.application.Sphinx.add_source_suffix()` + - :meth:`~sphinx.application.Sphinx.add_source_suffix` * - ``BuildEnvironment.load()`` @@ -1792,7 +1792,7 @@ The following is a list of deprecated interfaces. * - :confval:`!source_parsers` - 1.8 - 3.0 - - :meth:`~sphinx.application.Sphinx.add_source_parser()` + - :meth:`~sphinx.application.Sphinx.add_source_parser` * - ``sphinx.util.docutils.directive_helper()`` - 1.8 @@ -1812,17 +1812,17 @@ The following is a list of deprecated interfaces. * - ``sphinx.locale.l_()`` - 1.8 - 3.0 - - :func:`sphinx.locale._()` + - :func:`sphinx.locale._` * - ``sphinx.locale.lazy_gettext()`` - 1.8 - 3.0 - - :func:`sphinx.locale._()` + - :func:`sphinx.locale._` * - ``sphinx.locale.mygettext()`` - 1.8 - 3.0 - - :func:`sphinx.locale._()` + - :func:`sphinx.locale._` * - ``sphinx.util.copy_static_entry()`` - 1.5 @@ -1857,17 +1857,17 @@ The following is a list of deprecated interfaces. * - ``sphinx.ext.autodoc.add_documenter()`` - 1.7 - 2.0 - - :meth:`~sphinx.application.Sphinx.add_autodocumenter()` + - :meth:`~sphinx.application.Sphinx.add_autodocumenter` * - ``sphinx.ext.autodoc.AutoDirective._register`` - 1.7 - 2.0 - - :meth:`~sphinx.application.Sphinx.add_autodocumenter()` + - :meth:`~sphinx.application.Sphinx.add_autodocumenter` * - ``AutoDirective._special_attrgetters`` - 1.7 - 2.0 - - :meth:`~sphinx.application.Sphinx.add_autodoc_attrgetter()` + - :meth:`~sphinx.application.Sphinx.add_autodoc_attrgetter` * - ``Sphinx.warn()``, ``Sphinx.info()`` - 1.6 diff --git a/doc/extdev/domainapi.rst b/doc/extdev/domainapi.rst index d70b5db751d..bb5100de020 100644 --- a/doc/extdev/domainapi.rst +++ b/doc/extdev/domainapi.rst @@ -13,6 +13,10 @@ Domain API .. autoclass:: Index :members: +.. autoclass:: IndexEntry + :members: + :member-order: bysource + .. module:: sphinx.directives .. autoclass:: ObjectDescription diff --git a/doc/extdev/parserapi.rst b/doc/extdev/parserapi.rst index c5db2ac9792..b5480996065 100644 --- a/doc/extdev/parserapi.rst +++ b/doc/extdev/parserapi.rst @@ -12,7 +12,7 @@ __ https://docutils.sourceforge.io/docs/dev/hacking.html#parsing-the-document In Sphinx, the parser modules works as same as docutils. The parsers are registered to Sphinx by extensions using Application APIs; -:meth:`.Sphinx.add_source_suffix()` and :meth:`.Sphinx.add_source_parser()`. +:meth:`.Sphinx.add_source_suffix` and :meth:`.Sphinx.add_source_parser`. The *source suffix* is a mapping from file suffix to file type. For example, ``.rst`` file is mapped to ``'restructuredtext'`` type. Sphinx uses the diff --git a/doc/latex.rst b/doc/latex.rst index 5c9c503565b..fce61480941 100644 --- a/doc/latex.rst +++ b/doc/latex.rst @@ -4,6 +4,9 @@ LaTeX customization .. module:: latex :synopsis: LaTeX specifics. +.. role:: code-tex(code) + :language: LaTeX + .. _contents: https://docutils.sourceforge.io/docs/ref/rst/directives.html#table-of-contents .. raw:: latex @@ -120,7 +123,7 @@ Keys that you may want to override include: ``'passoptionstopackages'`` A string which will be positioned early in the preamble, designed to - contain ``\\PassOptionsToPackage{options}{foo}`` commands. + contain :code-tex:`\\PassOptionsToPackage{options}{foo}` commands. .. hint:: @@ -133,7 +136,7 @@ Keys that you may want to override include: .. versionadded:: 1.4 ``'babel'`` - "babel" package inclusion, default ``'\\usepackage{babel}'`` (the + "babel" package inclusion, default :code-tex:`r'\\usepackage{babel}'` (the suitable document language string is passed as class option, and ``english`` is used if no language.) For Japanese documents, the default is the empty string. @@ -152,7 +155,7 @@ Keys that you may want to override include: build repertory before next PDF build, else left-over auxiliary files are likely to break the build. - Default: ``'\\usepackage{babel}'`` (for Japanese documents) + Default: :code-tex:`r'\\usepackage{babel}'` (for Japanese documents) .. versionchanged:: 1.5 For :confval:`latex_engine` set to ``'xelatex'``, the default @@ -168,16 +171,21 @@ Keys that you may want to override include: .. versionchanged:: 7.4.0 For French with ``'lualatex'`` the default is to use ``babel``. +.. _fontpkg: + ``'fontpkg'`` - Font package inclusion. The default is:: + Font package inclusion. The default with ``'pdflatex'`` is:: r"""\usepackage{tgtermes} \usepackage{tgheros} \renewcommand\ttdefault{txtt} """ - For ``'xelatex'`` and ``'lualatex'`` however the default is to use - the GNU FreeFont. + For ``'xelatex'`` and ``'lualatex'`` on the other hand the + :code-tex:`\\setmainfont`, :code-tex:`\\setsansfont` and + :code-tex:`\\setmonofont` commands of LaTeX package ``fontspec`` (included + via :ref:`fontenc`) are used to set up the OpenType fonts GNU FreeSerif, + FreeSans, and FreeMono (scaled with ratio ``0.9``) as document fonts. .. versionchanged:: 1.2 Defaults to ``''`` when the :confval:`language` uses the Cyrillic @@ -186,29 +194,35 @@ Keys that you may want to override include: .. versionchanged:: 2.0 Incorporates some font substitution commands to help support occasional Greek or Cyrillic in a document using ``'pdflatex'`` engine. + At 4.0.0 these commands were moved to the ``'fontsubstitution'`` key. .. versionchanged:: 4.0.0 - - - The font substitution commands added at ``2.0`` have been moved - to the ``'fontsubstitution'`` key, as their presence here made - it complicated for user to customize the value of ``'fontpkg'``. - - The default font setting has changed: it still uses Times and - Helvetica clones for serif and sans serif, but via better, more - complete TeX fonts and associated LaTeX packages. The - monospace font has been changed to better match the Times clone. + The default font setting was changed. As shown above it still uses + Times and Helvetica clones for serif and sans serif, but via better, + more complete TeX fonts and associated LaTeX packages. The monospace + font has been changed to better match the Times clone. + + .. versionchanged:: 8.1.0 + The monospace font FreeMono used with Unicode engines is loaded at scale + ``0.9``. This replaces the former mechanism via :ref:`fvset` which + configured code-blocks to use :code-tex:`\\small`. Inline literals now + fit better in their surrounding text, and it is easier to set up custom + fonts, as :ref:`fvset` does not intervene anymore by default. ``'fncychap'`` Inclusion of the "fncychap" package (which makes fancy chapter titles), - default ``'\\usepackage[Bjarne]{fncychap}'`` for English documentation + default :code-tex:`r'\\usepackage[Bjarne]{fncychap}'` for English documentation (this option is slightly customized by Sphinx), - ``'\\usepackage[Sonny]{fncychap}'`` for internationalized docs (because + :code-tex:`r'\\usepackage[Sonny]{fncychap}'` for internationalized docs (because the "Bjarne" style uses numbers spelled out in English). Other "fncychap" styles you can try are "Lenny", "Glenn", "Conny", "Rejne" and "Bjornstrup". You can also set this to ``''`` to disable fncychap. - Default: ``'\\usepackage[Bjarne]{fncychap}'`` for English documents, - ``'\\usepackage[Sonny]{fncychap}'`` for internationalized documents, and - ``''`` for Japanese documents. + Default: :code-tex:`r'\\usepackage[Bjarne]{fncychap}'` for English + documents, :code-tex:`r'\\usepackage[Sonny]{fncychap}'` for + internationalized documents, and ``''`` for Japanese documents. + +.. _preamble: ``'preamble'`` Additional preamble content. One may move all needed macros into some file @@ -314,7 +328,7 @@ Keys that don't need to be overridden unless in special cases are: ``'inputenc'`` "inputenc" package inclusion. - Default: ``'\\usepackage[utf8]{inputenc}'`` when using pdflatex, else + Default: :code-tex:`r'\\usepackage[utf8]{inputenc}'` when using pdflatex, else ``''``. .. note:: @@ -340,67 +354,76 @@ Keys that don't need to be overridden unless in special cases are: ``utf8x`` is in use. .. versionchanged:: 1.4.3 - Previously ``'\\usepackage[utf8]{inputenc}'`` was used for all + Previously :code-tex:`r'\\usepackage[utf8]{inputenc}'` was used for all compilers. ``'cmappkg'`` "cmap" package inclusion. - Default: ``'\\usepackage{cmap}'`` + Default: :code-tex:`r'\\usepackage{cmap}'` .. versionadded:: 1.2 +.. _fontenc: + ``'fontenc'`` - Customize this from its default ``'\\usepackage[T1]{fontenc}'`` to: + Its default, for ``'pdflatex'`` as :confval:`latex_engine`, is + :code-tex:`r'\\usepackage[T1]{fontenc}'`. Replace it (if using + ``'pdflatex'``) with: - - ``'\\usepackage[X2,T1]{fontenc}'`` if you need occasional + - :code-tex:`r'\\usepackage[X2,T1]{fontenc}'` if you need occasional Cyrillic letters (физика частиц), - - ``'\\usepackage[LGR,T1]{fontenc}'`` if you need occasional - Greek letters (Σωματιδιακή φυσική). + - :code-tex:`r'\\usepackage[LGR,T1]{fontenc}'` if you need occasional + Greek letters (Σωματιδιακή φυσική), - Use ``[LGR,X2,T1]`` rather if both are needed. + - :code-tex:`r'\\usepackage[LGR,X2,T1]{fontenc}'` if you need both. - .. attention:: + The TeX installation may need some extra packages. For example, on Ubuntu + xenial: - - Do not use this key for a :confval:`latex_engine` other than - ``'pdflatex'``. + - ``texlive-lang-greek`` and ``cm-super`` are needed for Greek (``LGR``), - - If Greek is main language, do not use this key. Since Sphinx 2.2.1, - ``xelatex`` will be used automatically as :confval:`latex_engine`. + - ``texlive-lang-cyrillic`` and ``cm-super`` are needed for Cyrillic + (``X2``). - - The TeX installation may need some extra packages. For example, - on Ubuntu xenial, packages ``texlive-lang-greek`` and ``cm-super`` - are needed for ``LGR`` to work. And ``texlive-lang-cyrillic`` and - ``cm-super`` are needed for support of Cyrillic. + With ``'xelatex'`` and ``'lualatex'``, support for Greek and Cyrillic is + out-of-the-box: this :ref:`fontenc` key defaults to including the LaTeX + package ``fontspec`` (with some extras described below) and selects the GNU + FreeSerif font as body font. See :ref:`fontpkg`. .. versionchanged:: 1.5 - Defaults to ``'\\usepackage{fontspec}'`` when - :confval:`latex_engine` is ``'xelatex'``. + Defaults to :code-tex:`r'\\usepackage{fontspec}'` if + :confval:`latex_engine` is set to ``'xelatex'``. .. versionchanged:: 1.6 - ``'lualatex'`` uses ``fontspec`` per default like ``'xelatex'``. + Defaults to :code-tex:`r'\\usepackage{fontspec}'` if + :confval:`latex_engine` is set to ``'lualatex'``. .. versionchanged:: 2.0 - ``'lualatex'`` executes - ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` to disable TeX - ligatures transforming ``<<`` and ``>>`` as escaping working with - ``pdflatex/xelatex`` failed with ``lualatex``. + ``'lualatex'`` executes additionally + :code-tex:`\\defaultfontfeatures[\\rmfamily,\\sffamily]{}` to disable TeX + ligatures for ``<<`` and ``>>``. .. versionchanged:: 2.0 - Detection of ``LGR``, ``T2A``, ``X2`` to trigger support of - occasional Greek or Cyrillic letters (``'pdflatex'``). + Extra LaTeX configuration is automatically executed if ``LGR``, ``T2A``, + or ``X2`` are detected in this key, in order to support occasional Greek + or Cyrillic with ``'pdflatex'``. + + .. versionchanged:: 2.2.1 + Documents having Greek as main language default to ``'xelatex'`` and + should not set the :ref:`fontenc` key, which will load ``fontspec``. .. versionchanged:: 2.3.0 ``'xelatex'`` executes - ``\defaultfontfeatures[\rmfamily,\sffamily]{}`` in order to avoid - contractions of ``--`` into en-dash or transforms of straight quotes - into curly ones in PDF (in non-literal text paragraphs) despite - :confval:`smartquotes` being set to ``False``. + :code-tex:`\\defaultfontfeatures[\\rmfamily,\\sffamily]{}` in order to + avoid contractions of ``--`` into en-dash and also transforms of + straight quotes into curly quotes (which otherwise would happen even + with :confval:`smartquotes` set to ``False``). ``'fontsubstitution'`` Ignored if ``'fontenc'`` was not configured to use ``LGR`` or ``X2`` (or - ``T2A``). In case ``'fontpkg'`` key is configured for usage with some + ``T2A``). In case :ref:`fontpkg` key is configured for usage with some TeX fonts known to be available in the ``LGR`` or ``X2`` encodings, set this one to be the empty string. Else leave to its default. @@ -413,7 +436,7 @@ Keys that don't need to be overridden unless in special cases are: It is ignored with ``'platex'``, ``'xelatex'`` or ``'lualatex'`` as :confval:`latex_engine` and defaults to either the empty string or - to ``'\\usepackage{textalpha}'`` for ``'pdflatex'`` depending on + to :code-tex:`r'\\usepackage{textalpha}'` for ``'pdflatex'`` depending on whether the ``'fontenc'`` key was used with ``LGR`` or not. Only expert LaTeX users may want to customize this key. @@ -421,20 +444,16 @@ Keys that don't need to be overridden unless in special cases are: ``'pdflatex'`` support Greek Unicode input in :rst:dir:`math` context. For example ``:math:`α``` (U+03B1) will render as :math:`\alpha`. - Default: ``'\\usepackage{textalpha}'`` or ``''`` if ``fontenc`` does not + Default: :code-tex:`r'\\usepackage{textalpha}'` or ``''`` if ``fontenc`` does not include the ``LGR`` option. .. versionadded:: 2.0 ``'geometry'`` - "geometry" package inclusion, the default definition is: - - .. code-block:: latex - - '\\usepackage{geometry}' - - with an additional ``[dvipdfm]`` for Japanese documents. - The Sphinx LaTeX style file executes: + "geometry" package inclusion, defaults to + :code-tex:`r'\\usepackage{geometry}'` or + :code-tex:`r'\\usepackage[dvipdfm]{geometry}'` for Japanese documents. + The Sphinx LaTeX style file executes additionally: .. code-block:: latex @@ -443,9 +462,6 @@ Keys that don't need to be overridden unless in special cases are: which can be customized via corresponding :ref:`'sphinxsetup' options `. - Default: ``'\\usepackage{geometry}'`` (or - ``'\\usepackage[dvipdfm]{geometry}'`` for Japanese documents) - .. versionadded:: 1.5 .. versionchanged:: 1.5.2 @@ -457,8 +473,9 @@ Keys that don't need to be overridden unless in special cases are: .. versionchanged:: 1.5.3 The location in the LaTeX file has been moved to after - ``\usepackage{sphinx}`` and ``\sphinxsetup{..}``, hence also after - insertion of ``'fontpkg'`` key. This is in order to handle the paper + :code-tex:`\\usepackage{sphinx}` and :code-tex:`\\sphinxsetup{..}`, + hence also after + insertion of :ref:`fontpkg` key. This is in order to handle the paper layout options in a special way for Japanese documents: the text width will be set to an integer multiple of the *zenkaku* width, and the text height to an integer multiple of the baseline. See the @@ -466,8 +483,8 @@ Keys that don't need to be overridden unless in special cases are: ``'hyperref'`` "hyperref" package inclusion; also loads package "hypcap" and issues - ``\urlstyle{same}``. This is done after :file:`sphinx.sty` file is - loaded and before executing the contents of ``'preamble'`` key. + :code-tex:`\\urlstyle{same}`. This is done after :file:`sphinx.sty` file + is loaded and before executing the contents of ``'preamble'`` key. .. attention:: @@ -483,18 +500,18 @@ Keys that don't need to be overridden unless in special cases are: .. hint:: If the key value is set to - ``r'\newcommand\sphinxbackoftitlepage{}\sphinxmaketitle'``, then ```` will be + :code-tex:`r'\\newcommand\sphinxbackoftitlepage{}\\sphinxmaketitle'`, then ```` will be typeset on back of title page (``'manual'`` docclass only). - Default: ``'\\sphinxmaketitle'`` + Default: :code-tex:`r'\\sphinxmaketitle'` .. versionchanged:: 1.8.3 - Original ``\maketitle`` from document class is not overwritten, + Original :code-tex:`\\maketitle` from document class is not overwritten, hence is reusable as part of some custom setting for this key. .. versionadded:: 1.8.3 - ``\sphinxbackoftitlepage`` optional macro. It can also be defined + :code-tex:`\\sphinxbackoftitlepage` optional macro. It can also be defined inside ``'preamble'`` key rather than this one. ``'releasename'`` @@ -505,72 +522,84 @@ Keys that don't need to be overridden unless in special cases are: Default: ``'Release'`` ``'tableofcontents'`` - "tableofcontents" call. The default of ``'\\sphinxtableofcontents'`` is a - wrapper of unmodified ``\tableofcontents``, which may itself be customized - by user loaded packages. Override if you want to generate a different table - of contents or put content between the title page and the TOC. + "tableofcontents" call. The default of + :code-tex:`r'\\sphinxtableofcontents'` is a wrapper of unmodified + :code-tex:`\\tableofcontents`, which may itself be customized by user + loaded packages. Override if you want to generate a different table of + contents or put content between the title page and the TOC. - Default: ``'\\sphinxtableofcontents'`` + Default: :code-tex:`r'\\sphinxtableofcontents'` .. versionchanged:: 1.5 - Previously the meaning of ``\tableofcontents`` itself was modified - by Sphinx. This created an incompatibility with dedicated packages - modifying it also such as "tocloft" or "etoc". + Previously the meaning of :code-tex:`\\tableofcontents` itself was + modified by Sphinx. This created an incompatibility with dedicated + packages modifying it also such as "tocloft" or "etoc". ``'transition'`` Commands used to display transitions. Override if you want to display transitions differently. - Default: ``'\n\n\\bigskip\\hrule\\bigskip\n\n'`` + Default: :code-tex:`'\\n\\n\\\\bigskip\\\\hrule\\\\bigskip\\n\\n'` .. versionadded:: 1.2 .. versionchanged:: 1.6 - Remove unneeded ``{}`` after ``\\hrule``. + Remove unneeded ``{}`` formerly located after :code-tex:`\\hrule`. ``'makeindex'`` "makeindex" call, the last thing before ``\begin{document}``. With - ``'\\usepackage[columns=1]{idxlayout}\\makeindex'`` the index will use - only one column. You may have to install ``idxlayout`` LaTeX package. + :code-tex:`r'\\usepackage[columns=1]{idxlayout}\\makeindex'` the index will + use only one column. You may have to install ``idxlayout`` LaTeX package. - Default: ``'\\makeindex'`` + Default: :code-tex:`r'\\makeindex'` ``'printindex'`` "printindex" call, the last thing in the file. Override if you want to generate the index differently, append some content after the index, or - change the font. As LaTeX uses two-column mode for the index it is - often advisable to set this key to - ``'\\footnotesize\\raggedright\\printindex'``. Or, to obtain a one-column - index, use ``'\\def\\twocolumn[#1]{#1}\\printindex'`` (this trick may fail - if using a custom document class; then try the ``idxlayout`` approach - described in the documentation of the ``'makeindex'`` key). + change the font. As LaTeX uses two-column mode for the index it is often + advisable to set this key to + :code-tex:`r'\\footnotesize\\raggedright\\printindex'`. Or, to obtain a + one-column index, use :code-tex:`r'\\def\\twocolumn[#1]{#1}\\printindex'` + (this trick may fail if using a custom document class; then try the + ``idxlayout`` approach described in the documentation of the + ``'makeindex'`` key). + + Default: :code-tex:`r'\\printindex'` - Default: ``'\\printindex'`` +.. _fvset: ``'fvset'`` Customization of ``fancyvrb`` LaTeX package. - The default value is ``'\\fvset{fontsize=auto}'`` which means that the - font size will adjust correctly if a code-block ends up in a footnote. - You may need to modify this if you use custom fonts: - ``'\\fvset{fontsize=\\small}'`` if the monospace font is Courier-like. + The default value is :code-tex:`r'\\fvset{fontsize=auto}'` which means that + the font size will adjust correctly if a code-block ends up in a footnote. + You may need to modify this when using a custom monospace font, for example + set it to :code-tex:`r'\\fvset{fontsize=\\small}'` if it is Courier-like + (for Unicode engines, it is recommended to use rather the ``Scale`` + interface of :code-tex:`\\setmonofont` LaTeX command from ``fontspec``). - Default: ``'\\fvset{fontsize=auto}'`` + Default: :code-tex:`r'\\fvset{fontsize=auto}'` .. versionadded:: 1.8 .. versionchanged:: 2.0 For ``'xelatex'`` and ``'lualatex'`` defaults to - ``'\\fvset{fontsize=\\small}'`` as this + :code-tex:`r'\\fvset{fontsize=\\small}'` as this is adapted to the relative widths of the FreeFont family. .. versionchanged:: 4.0.0 Changed default for ``'pdflatex'``. Previously it was using - ``'\\fvset{fontsize=\\small}'``. + :code-tex:`r'\\fvset{fontsize=\\small}'`. .. versionchanged:: 4.1.0 Changed default for Chinese documents to - ``'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'`` + :code-tex:`r'\\fvset{fontsize=\\small,formatcom=\\xeCJKVerbAddon}'` + + .. versionchanged:: 8.1.0 + Changed default for ``'xelatex'`` and ``'lualatex'`` to be also + :code-tex:`r'\\fvset{fontsize=auto}'`. The rescaling for default + monospace font FreeMono is now set via the LaTeX package ``fontspec`` + interface rather. See :ref:`fontpkg`. Keys that are set by other options and therefore should not be overridden are: @@ -683,8 +712,9 @@ The color used in the above example is available from having passed the .. versionadded:: 1.5.3 ``marginpar`` - The ``\marginparwidth`` LaTeX dimension. For Japanese documents, the value - is modified to be the closest integer multiple of the *zenkaku* width. + The :code-tex:`\\marginparwidth` LaTeX dimension. For Japanese documents, + the value is modified to be the closest integer multiple of the *zenkaku* + width. Default: ``0.5in`` @@ -821,9 +851,11 @@ The color used in the above example is available from having passed the ``verbatimcontinued`` A LaTeX macro inserted at start of continuation code lines. Its - (complicated...) default typesets a small red hook pointing to the right:: + (complicated...) default typesets a small red hook pointing to the right: - \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}} + .. code-block:: latex + + \makebox[2\fontcharwd\font`\x][r]{\textcolor{red}{\tiny$\hookrightarrow$}} .. versionchanged:: 1.5 The breaking of long code lines was added at 1.4.2. The default @@ -834,12 +866,12 @@ The color used in the above example is available from having passed the Values for color keys must either: - - obey the syntax of the ``\definecolor`` LaTeX command, e.g. something + - obey the syntax of the :code-tex:`\\definecolor` LaTeX command, e.g. something such as ``VerbatimColor={rgb}{0.2,0.3,0.5}`` or ``{RGB}{37,23,255}`` or ``{gray}{0.75}`` or ``{HTML}{808080}`` or ... - - or obey the syntax of the ``\colorlet`` command from package ``xcolor`` + - or obey the syntax of the :code-tex:`\\colorlet` command from package ``xcolor`` e.g. ``VerbatimColor=red!10`` or ``red!50!green`` or ``-red!75`` or ``MyPreviouslyDefinedColor`` or... Refer to xcolor_ documentation for this syntax. @@ -847,7 +879,7 @@ The color used in the above example is available from having passed the .. _xcolor: https://ctan.org/pkg/xcolor .. versionchanged:: 5.3.0 - Formerly only the ``\definecolor`` syntax was accepted. + Formerly only the :code-tex:`\\definecolor` syntax was accepted. ``TitleColor`` The color for titles (as configured via use of package "titlesec".) @@ -901,9 +933,10 @@ The color used in the above example is available from having passed the class. It is ignored for tables with ``nocolorrows`` class. As for the other ``'sphinxsetup'`` keys, it can also be set or modified - from a ``\sphinxsetup{...}`` LaTeX command inserted via the :dudir:`raw` - directive, or also from a LaTeX environment associated to a `container - class `_ and using such ``\sphinxsetup{...}``. + from a :code-tex:`\\sphinxsetup{...}` LaTeX command inserted via the + :dudir:`raw` directive, or also from a LaTeX environment associated to a + `container class `_ and using such + :code-tex:`\\sphinxsetup{...}`. Default: ``{gray}{0.86}`` @@ -939,13 +972,13 @@ The color used in the above example is available from having passed the See :ref:`additionalcss` for its alias ``pre_padding`` and additional keys. - Default: ``\fboxsep`` + Default: :code-tex:`\\fboxsep` ``verbatimborder`` The width of the frame around :rst:dir:`code-block`\ s. See also :ref:`additionalcss` for ``pre_border-width``. - Default: ``\fboxrule`` + Default: :code-tex:`\\fboxrule` .. important:: @@ -1017,8 +1050,8 @@ The color used in the above example is available from having passed the which supports the customizability described in :ref:`additionalcss`. |notetexextras| - Some extra LaTeX code (such as ``\bfseries`` or ``\footnotesize``) - to be executed at start of the contents. + Some extra LaTeX code (such as :code-tex:`\\bfseries` or + :code-tex:`\\footnotesize`) to be executed at start of the contents. Default: empty @@ -1072,18 +1105,18 @@ The color used in the above example is available from having passed the LaTeX macros inserted at the start of the footnote text at bottom of page, after the footnote number. - Default: ``\mbox{ }`` + Default: :code-tex:`\\mbox{ }` ``BeforeFootnote`` LaTeX macros inserted before the footnote mark. The default removes possible space before it (else, TeX could insert a line break there). - Default: ``\leavevmode\unskip`` + Default: :code-tex:`\\leavevmode\\unskip` .. versionadded:: 1.5 ``HeaderFamily`` - default ``\sffamily\bfseries``. Sets the font used by headings. + default :code-tex:`\\sffamily\\bfseries`. Sets the font used by headings. .. |notebdcolors| replace:: ``noteBorderColor``, ``hintBorderColor``, @@ -1157,15 +1190,15 @@ Additional CSS-like ``'sphinxsetup'`` keys Perhaps in future these 5.1.0 (and 6.2.0) novel settings will be optionally imported from some genuine CSS external file, but currently they have to be used -via the ``'sphinxsetup'`` interface (or the ``\sphinxsetup`` LaTeX command +via the ``'sphinxsetup'`` interface (or the :code-tex:`\\sphinxsetup` LaTeX command inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated. .. important:: Low-level LaTeX errors causing a build failure can happen if the input syntax is not respected. * In particular colors must be input as for the other color related options - previously described, i.e. either in the ``\definecolor`` syntax or via the - ``\colorlet`` syntax:: + previously described, i.e. either in the :code-tex:`\\definecolor` syntax + or via the :code-tex:`\\colorlet` syntax:: ... div.warning_border-TeXcolor={rgb}{1,0,0},% \definecolor syntax @@ -1185,17 +1218,18 @@ inserted via the :dudir:`raw` directive) and the CSS syntax is only imitated. but not by ``xelatex`` or ``platex``. * It is allowed for such specifications to be so-called "dimensional - expressions", e.g. ``\fboxsep+2pt`` or ``0.5\baselineskip`` are valid - inputs. The expressions will be evaluated only at the typesetting time. - Be careful though if using as in these examples TeX control sequences to - double the backslash or to employ a raw Python string for the value of - the :ref:`'sphinxsetup' ` key. + expressions", e.g. :code-tex:`\\fboxsep+2pt` or + :code-tex:`0.5\\baselineskip` are valid inputs. The expressions will be + evaluated only at the typesetting time. Be careful though if using as in + these examples TeX control sequences to double the backslash or to employ + a raw Python string for the value of the :ref:`'sphinxsetup' + ` key. * As a rule, avoid inserting unneeded spaces in the key values: especially - for the radii an input such ``2 pt 3pt`` will break LaTeX. Beware also - that ``\fboxsep \fboxsep`` will not be seen as space separated in LaTeX. - You must use something such as ``{\fboxsep} \fboxsep``. Or use - directly ``3pt 3pt`` which is a priori equivalent and simpler. + for the radii an input such ``2 pt 3pt`` will break LaTeX. Beware also + that :code-tex:`\\fboxsep \\fboxsep` will not be seen as space separated + in LaTeX. You must use something such as ``{\fboxsep} \fboxsep``. Or + use directly ``3pt 3pt`` which is a priori equivalent and simpler. The options are all named in a similar pattern which depends on a ``prefix``, which is then followed by an underscore, then the property name. @@ -1351,14 +1385,14 @@ forget the underscore separating the prefix from the property names. Consider passing options such as ``dvipsnames``, ``svgnames`` or ``x11names`` to ``xcolor`` via ``'passoptionstopackages'`` key of :confval:`latex_elements`. - If ``_TeXcolor`` is set, a ``\color`` command is inserted at + If ``_TeXcolor`` is set, a :code-tex:`\\color` command is inserted at start of the directive contents; for admonitions, this happens after the heading which reproduces the admonition type. - ``_TeXextras``: if set, its value must be some LaTeX command or - commands, for example ``\itshape``. These commands will be inserted at the - start of the contents; for admonitions, this happens after the heading which - reproduces the admonition type. + commands, for example :code-tex:`\\itshape`. These commands will be + inserted at the start of the contents; for admonitions, this happens after + the heading which reproduces the admonition type. The next keys, for admonitions, :dudir:`topic`, contents_, and :dudir:`sidebar`, were all three added at 7.4.0 (and 8.1.0 for the latter three). @@ -1368,8 +1402,9 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and .. important:: The colored title-row is produced as a result of the Sphinx default - definitions for the various ``\sphinxstyletitle`` commands, which - employ the ``\sphinxdotitlerow`` LaTeX command. See :ref:`latex-macros`. + definitions for the various :code-tex:`\\sphinxstyletitle` + commands, which employ the :code-tex:`\\sphinxdotitlerow` LaTeX command. + See :ref:`latex-macros`. - ``div._title-foreground-TeXcolor``: the color to be used for the icon (it applies only to the icon, not to the title of the admonition). @@ -1380,11 +1415,12 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and LaTeX ``fontawesome5`` package, which is loaded automatically if available. If neither ``fontawesome5`` nor fall-back ``fontawesome`` (for which the - associated command is ``\faicon``, not ``\faIcon``) are found, or if the - ``iconpackage`` key of :ref:`'sphinxsetup' ` is set to - load some other user-chosen package, or no package at all, all the - ``title-icons`` default to empty LaTeX code. It is up to user to employ - this interface to inject the icon (or anything else) into the PDF output. + associated command is :code-tex:`\\faicon`, not :code-tex:`\\faIcon`) are + found, or if the ``iconpackage`` key of :ref:`'sphinxsetup' + ` is set to load some other user-chosen package, or no + package at all, all the ``title-icons`` default to empty LaTeX code. It is + up to user to employ this interface to inject the icon (or anything else) + into the PDF output. .. note:: @@ -1420,18 +1456,12 @@ The next keys, for admonitions, :dudir:`topic`, contents_, and tokens; it does color the line numbers, but if one wants to color *only* them one has to go through the ``fancyvrb`` interface. - - ``pre_TeXextras=\footnotesize`` for example may be replaced by usage of - the :confval:`latex_elements` key ``'fvset'``. For ``'lualatex'`` or - ``'xelatex'`` Sphinx includes in the preamble already - ``\fvset{fontsize=\small}`` and this induces ``fancyvrb`` into - overriding a ``\footnotesize`` coming from ``pre_TeXextras``. One has - to use ``pre_TeXextras=\fvset{fontsize=\footnotesize}`` syntax. - Simpler to set directly the :confval:`latex_elements` key - ``'fvset'``... + - ``pre_TeXextras=\footnotesize`` (as an example) is equivalent to setting + :ref:`fvset` key value to :code-tex:`r'\\fvset{fontsize=\\footnotesize}'`. Consider these options experimental and that some implementation details may change. For example if the ``pre_TeXextras`` LaTeX commands were put - by Sphinx in another location it could override the ``'fvset'`` effect, + by Sphinx in another location it could override the :ref:`fvset` effect, perhaps this is what will be done in a future release. - Rounded boxes are done using the pict2e_ interface to some basic PDF @@ -1530,25 +1560,26 @@ Macros with LaTeX packages. .. versionadded:: 1.8 - ``\sphinxguilabel`` + :code-tex:`\\sphinxguilabel` .. versionadded:: 3.0 - ``\sphinxkeyboard`` + :code-tex:`\\sphinxkeyboard` .. versionadded:: 6.2.0 - ``\sphinxparam``, ``\sphinxsamedocref`` + :code-tex:`\\sphinxparam`, :code-tex:`\\sphinxsamedocref` .. versionadded:: 7.1.0 - ``\sphinxparamcomma`` which defaults to a comma followed by a space and - ``\sphinxparamcommaoneperline`` which is used for one-parameter-per-line - signatures (see :confval:`maximum_signature_line_length`). It defaults - to ``\texttt{,}`` to make these end-of-line separators more distinctive. - - Signatures of Python functions are rendered as ``name(parameters)`` - or ``name[type parameters](parameters)`` (see :pep:`695`) - where the length of ```` is set to ``0pt`` by default. - This can be changed via ``\setlength{\sphinxsignaturelistskip}{1ex}`` - for instance. + :code-tex:`\\sphinxparamcomma` which defaults to a comma followed by a + space and :code-tex:`\\sphinxparamcommaoneperline`. It is sed for + one-parameter-per-line signatures (see + :confval:`maximum_signature_line_length`) and defaults to + :code-tex:`\\texttt{,}`. + + Signatures of Python functions are rendered as + ``name(parameters)`` or ``name[type + parameters](parameters)`` (see :pep:`695`) where the length of + ```` is set to ``0pt`` by default. This can be changed via + :code-tex:`\\setlength{\\sphinxsignaturelistskip}{1ex}` for instance. - More text styling: @@ -1595,7 +1626,7 @@ Macros .. note:: To let this table fit on the page width in PDF output we have lied a bit. - For instance, the actual definition of ``\sphinxstylenotetitle`` is: + For instance, the actual definition of :code-tex:`\\sphinxstylenotetitle` is: .. code-block:: latex @@ -1604,90 +1635,98 @@ Macros The same remark applies to all other similar commands associated with admonitions. The :dudir:`topic`, contents_, and :dudir:`sidebar` do not - use ``\sphinxremovefinalcolon`` as they don't need it. + use :code-tex:`\\sphinxremovefinalcolon` as they don't need it. .. versionadded:: 1.5 - These macros were formerly hard-coded as non customizable ``\texttt``, - ``\emph``, etc... + These macros were formerly hard-coded as non customizable :code-tex:`\\texttt`, + :code-tex:`\\emph`, etc... .. versionadded:: 1.6 - ``\sphinxstyletheadfamily`` which defaults to ``\sffamily`` and allows + :code-tex:`\\sphinxstyletheadfamily` which defaults to + :code-tex:`\\sffamily` and allows multiple paragraphs in header cells of tables. .. versionadded:: 1.6.3 - ``\sphinxstylecodecontinued`` and ``\sphinxstylecodecontinues``. + :code-tex:`\\sphinxstylecodecontinued` and + :code-tex:`\\sphinxstylecodecontinues`. .. versionadded:: 1.8 - ``\sphinxstyleindexlettergroup``, ``\sphinxstyleindexlettergroupDefault``. + :code-tex:`\\sphinxstyleindexlettergroup`, + :code-tex:`\\sphinxstyleindexlettergroupDefault`. .. versionadded:: 6.2.0 - ``\sphinxstylenotetitle`` et al. The ``#1`` is the localized name of the - directive, with a final colon. Wrap it as ``\sphinxremovefinalcolon{#1}`` - if this final colon is to be removed. + :code-tex:`\\sphinxstylenotetitle` et al. The ``#1`` is the localized + name of the directive, with a final colon. Wrap it as + :code-tex:`\\sphinxremovefinalcolon{#1}` if this final colon is to be + removed. .. versionadded:: 7.4.0 - Added the ``\sphinxdotitlerowwithicon`` LaTeX command. + Added the :code-tex:`\\sphinxdotitlerowwithicon` LaTeX command. .. versionchanged:: 8.1.0 - ``\sphinxdotitlerowwithicon`` now detects automatically if an icon is + :code-tex:`\\sphinxdotitlerowwithicon` now detects automatically if an icon is associated or not with the rendered element used as first argument. - .. versionadded:: 8.1.0 - Make ``\sphinxdotitlerow`` an alias to ``\sphinxdotitlerowwithicon``. + .. versionadded:: 8.1.0 Make :code-tex:`\\sphinxdotitlerow` an alias to + :code-tex:`\\sphinxdotitlerowwithicon`. .. versionadded:: 8.1.0 Titles of :dudir:`topic`, contents_, and :dudir:`sidebar` directives are - also styled using ``\sphinxdotitlerow`` (they have no default icons + also styled using :code-tex:`\\sphinxdotitlerow` (they have no default icons associated with them). -- ``\sphinxtableofcontents``: A wrapper (defined differently in +- :code-tex:`\\sphinxtableofcontents`: A wrapper (defined differently in :file:`sphinxhowto.cls` and in :file:`sphinxmanual.cls`) of standard - ``\tableofcontents``. The macro ``\sphinxtableofcontentshook`` is executed - during its expansion right before ``\tableofcontents`` itself. + :code-tex:`\\tableofcontents`. The macro + :code-tex:`\\sphinxtableofcontentshook` is executed during its expansion right + before :code-tex:`\\tableofcontents` itself. .. versionchanged:: 1.5 - Formerly, the meaning of ``\tableofcontents`` was modified by Sphinx. + Formerly, the meaning of :code-tex:`\\tableofcontents` was modified by Sphinx. .. versionchanged:: 2.0 - Hard-coded redefinitions of ``\l@section`` and ``\l@subsection`` formerly - done during loading of ``'manual'`` docclass are now executed later via - ``\sphinxtableofcontentshook``. This macro is also executed by the - ``'howto'`` docclass, but defaults to empty with it. + Hard-coded redefinitions of :code-tex:`\\l@section` and + :code-tex:`\\l@subsection` formerly done during loading of ``'manual'`` + docclass are now executed later via + :code-tex:`\\sphinxtableofcontentshook`. This macro is also executed by + the ``'howto'`` docclass, but defaults to empty with it. .. hint:: If adding to preamble the loading of ``tocloft`` package, also add to - preamble ``\renewcommand\sphinxtableofcontentshook{}`` else it will reset - ``\l@section`` and ``\l@subsection`` cancelling ``tocloft`` customization. + preamble :code-tex:`\\renewcommand\sphinxtableofcontentshook{}` else it + will reset :code-tex:`\\l@section` and :code-tex:`\\l@subsection` + cancelling ``tocloft`` customization. -- ``\sphinxmaketitle``: Used as the default setting of the ``'maketitle'`` +- :code-tex:`\\sphinxmaketitle`: Used as the default setting of the ``'maketitle'`` :confval:`latex_elements` key. Defined in the class files :file:`sphinxmanual.cls` and :file:`sphinxhowto.cls`. .. versionchanged:: 1.8.3 - Formerly, ``\maketitle`` from LaTeX document class was modified by + Formerly, :code-tex:`\\maketitle` from LaTeX document class was modified by Sphinx. -- ``\sphinxbackoftitlepage``: For ``'manual'`` docclass, and if it is - defined, it gets executed at end of ``\sphinxmaketitle``, before the final - ``\clearpage``. Use either the ``'maketitle'`` key or the ``'preamble'`` key - of :confval:`latex_elements` to add a custom definition of - ``\sphinxbackoftitlepage``. +- :code-tex:`\\sphinxbackoftitlepage`: For ``'manual'`` docclass, and if it is + defined, it gets executed at end of :code-tex:`\\sphinxmaketitle`, before + the final :code-tex:`\\clearpage`. Use either the ``'maketitle'`` key or + the ``'preamble'`` key of :confval:`latex_elements` to add a custom + definition of :code-tex:`\\sphinxbackoftitlepage`. .. versionadded:: 1.8.3 -- ``\sphinxcite``: A wrapper of standard ``\cite`` for citation references. +- :code-tex:`\\sphinxcite`: A wrapper of standard :code-tex:`\\cite` for + citation references. .. _sphinxbox: -The ``\sphinxbox`` command -~~~~~~~~~~~~~~~~~~~~~~~~~~ +The :code-tex:`\\sphinxbox` command +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. versionadded:: 6.2.0 -The ``\sphinxbox[key=value,...]{inline text}`` command can be used to "box" +The :code-tex:`\\sphinxbox[key=value,...]{inline text}` command can be used to "box" inline text elements with all the customizability which has been described in :ref:`additionalcss`. It is a LaTeX command with one optional argument, which is a comma-separated list of key=value pairs, as for :ref:`latexsphinxsetup`. @@ -1708,33 +1747,27 @@ Here is the complete list of keys. They don't use any prefix. - and ``addstrut`` which is a boolean key, i.e. to be used as ``addstrut=true``, or ``addstrut`` alone where ``=true`` is omitted, or ``addstrut=false``. -This last key is specific to ``\sphinxbox`` and it means to add a ``\strut`` -so that heights and depths are equalized across various instances on the same -line with varying contents. The default is ``addstrut=false``. - -.. important:: - - Perhaps the default will turn into ``addstrut=true`` at 7.0.0 depending on - feedback until then. - -The combination ``addstrut, padding-bottom=0pt, padding-top=1pt`` is often -satisfactory. +This last key is specific to :code-tex:`\\sphinxbox` and it means to add a +:code-tex:`\\strut` so that heights and depths are equalized across various +instances on the same line with varying contents. The default is +``addstrut=false``. The combination ``addstrut, padding-bottom=0pt, +padding-top=1pt`` is often satisfactory. Refer to :ref:`additionalcss` for important syntax information regarding the -other keys. The default -configuration uses no shadow, a border-width of ``\fboxrule``, a padding of -``\fboxsep``, circular corners with radii ``\fboxsep`` and background and -border colors as for the default rendering of code-blocks. +other keys. The default configuration uses no shadow, a border-width of +:code-tex:`\\fboxrule`, a padding of :code-tex:`\\fboxsep`, circular corners +with radii :code-tex:`\\fboxsep` and background and border colors as for the +default rendering of code-blocks. -When a ``\sphinxbox`` usage is nested within another one, it will ignore the +When a :code-tex:`\\sphinxbox` usage is nested within another one, it will ignore the options of the outer one: it first resets all options to their default state as they were prior to applying the outer box options, then it applies its own specific ones. -One can modify these defaults via the command ``\sphinxboxsetup{key=value,...}``. -The effect is cumulative, if one uses this command multiple times. Here the -options are a mandatory argument so are within curly braces, not square -brackets. +One can modify these defaults via the command +:code-tex:`\\sphinxboxsetup{key=value,...}`. The effect is cumulative, if one +uses this command multiple times. Here the options are a mandatory argument +so are within curly braces, not square brackets. Here is some example of use: @@ -1751,9 +1784,9 @@ Here is some example of use: ''', } -A utility ``\newsphinxbox`` is provided to create a new boxing macro, say -``\foo`` which will act exactly like ``\sphinxbox`` but with a given extra -configuration: +A utility :code-tex:`\\newsphinxbox` is provided to create a new boxing macro, +say :code-tex:`\\foo` which will act exactly like :code-tex:`\\sphinxbox` but +with a given extra configuration: .. code-block:: latex @@ -1763,13 +1796,15 @@ configuration: \protected\def\sphinxguilabel#1{\foo{#1}} \protected\def\sphinxmenuselection#1{\foo[box-shadow-TeXcolor=gray]{#1}} -Boxes rendered with ``\foo`` obey as the ones using directly ``\sphinxbox`` -the current configuration as set possibly mid-way in document via -``\sphinxboxsetup`` (from a :dudir:`raw` LaTeX mark-up), the only difference -is that they have an initial additional set of default extras. +Boxes rendered with :code-tex:`\\foo` obey as the ones using directly +:code-tex:`\\sphinxbox` the current configuration as set possibly mid-way in +document via :code-tex:`\\sphinxboxsetup` (from a :dudir:`raw` LaTeX mark-up), +the only difference is that they have an initial additional set of default +extras. -In the above examples, you can probably use ``\renewcommand`` syntax if you -prefer it to ``\protected\def`` (with ``[1]`` in place of ``#1`` then). +In the above examples, you can probably use :code-tex:`\\renewcommand` syntax +if you prefer it to :code-tex:`\\protected\\def` (with ``[1]`` in place of +``#1`` then). Environments @@ -1777,11 +1812,11 @@ Environments - A :dudir:`figure` may have an optional legend with arbitrary body elements: they are rendered in a ``sphinxlegend`` environment. The default - definition issues ``\small``, and ends with ``\par``. + definition issues :code-tex:`\\small`, and ends with :code-tex:`\\par`. .. versionadded:: 1.5.6 - Formerly, the ``\small`` was hardcoded in LaTeX writer and the ending - ``\par`` was lacking. + Formerly, the :code-tex:`\\small` was hardcoded in LaTeX writer and the ending + :code-tex:`\\par` was lacking. - Environments associated with admonitions: @@ -1795,7 +1830,7 @@ Environments - ``sphinxdanger``, - ``sphinxerror``. - They may be ``\renewenvironment`` + They may be :code-tex:`\\renewenvironment` 'd individually, and must then be defined with one argument (it is the heading of the notice, for example ``Warning:`` for :dudir:`warning` directive, if English is the document language). Their default definitions use either the @@ -1861,7 +1896,7 @@ Environments .. versionadded:: 1.6.6 Easier customizability of the formatting via exposed to user LaTeX macros - such as ``\sphinxVerbatimHighlightLine``. + such as :code-tex:`\\sphinxVerbatimHighlightLine`. - The bibliography uses ``sphinxthebibliography`` and the Python Module index as well as the general index both use ``sphinxtheindex``; these environments @@ -1874,36 +1909,37 @@ Environments Miscellany ~~~~~~~~~~ -- Every text paragraph in document body starts with ``\sphinxAtStartPar``. +- Every text paragraph in document body starts with :code-tex:`\\sphinxAtStartPar`. Currently, this is used to insert a zero width horizontal skip which is a trick to allow TeX hyphenation of the first word of a paragraph in a narrow context (like a table cell). For ``'lualatex'`` which - does not need the trick, the ``\sphinxAtStartPar`` does nothing. + does not need the trick, the :code-tex:`\\sphinxAtStartPar` does nothing. .. versionadded:: 3.5.0 - The section, subsection, ... headings are set using *titlesec*'s - ``\titleformat`` command. + :code-tex:`\\titleformat` command. - For the ``'manual'`` docclass, the chapter headings can be customized using - *fncychap*'s commands ``\ChNameVar``, ``\ChNumVar``, ``\ChTitleVar``. File - :file:`sphinx.sty` has custom re-definitions in case of *fncychap* - option ``Bjarne``. + *fncychap*'s commands :code-tex:`\\ChNameVar`, :code-tex:`\\ChNumVar`, + :code-tex:`\\ChTitleVar`. File :file:`sphinx.sty` has custom re-definitions in + case of *fncychap* option ``Bjarne``. .. versionchanged:: 1.5 Formerly, use of *fncychap* with other styles than ``Bjarne`` was dysfunctional. - The :dudir:`role` directive allows to mark inline text with class arguments. - This is handled in LaTeX output via the ``\DUrole`` dispatcher command `as - in Docutils `_. Object signatures also use ``\DUrole`` for - some components, with one or two-letters class names as in HTML output. + This is handled in LaTeX output via the :code-tex:`\\DUrole` dispatcher + command `as in Docutils `_. Object signatures also use + :code-tex:`\\DUrole` for some components, with one or two-letters class + names as in HTML output. .. versionchanged:: 8.1.0 When multiple classes are injected via a a custom role, the LaTeX output - uses nested ``\DUrole``'s as in the `Docutils documentation - `_. Formerly it used a single ``\DUrole`` with comma - separated classes, making the LaTeX customization more arduous. + uses nested :code-tex:`\\DUrole`'s as in the `Docutils documentation + `_. Formerly it used a single :code-tex:`\\DUrole` with + comma separated classes, making the LaTeX customization more arduous. .. _classarguments: https://docutils.sourceforge.io/docs/user/latex.html#custom-interpreted-text-roles diff --git a/doc/man/sphinx-autogen.rst b/doc/man/sphinx-autogen.rst index 43cc369b78b..fed230d2cc1 100644 --- a/doc/man/sphinx-autogen.rst +++ b/doc/man/sphinx-autogen.rst @@ -14,7 +14,7 @@ that, using the :py:mod:`~sphinx.ext.autodoc` extension, document items included in :rst:dir:`autosummary` listing(s). *sourcefile* is the path to one or more reStructuredText documents containing -:rst:dir:`autosummary` entries with the ``:toctree::`` option set. *sourcefile* +:rst:dir:`autosummary` entries with the ``:toctree:`` option set. *sourcefile* can be an :py:mod:`fnmatch`-style pattern. Options diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst index a9e3a09cbfd..4c8fde48e96 100644 --- a/doc/man/sphinx-build.rst +++ b/doc/man/sphinx-build.rst @@ -126,8 +126,10 @@ Options .. option:: -j N, --jobs N Distribute the build over *N* processes in parallel, to make building on - multiprocessor machines more effective. Note that not all parts and not all - builders of Sphinx can be parallelized. If ``auto`` argument is given, + multiprocessor machines more effective. + This feature only works on systems supporting "fork". Windows is not supported. + Note that not all parts and not all builders of Sphinx can be parallelized. + If ``auto`` argument is given, Sphinx uses the number of CPUs as *N*. Defaults to 1. .. versionadded:: 1.2 diff --git a/doc/usage/configuration.rst b/doc/usage/configuration.rst index 5ffe2ea4a38..389a26d6013 100644 --- a/doc/usage/configuration.rst +++ b/doc/usage/configuration.rst @@ -1612,7 +1612,7 @@ and also make use of these options. The special attribute *priority* can be set as an integer to load the CSS file at an earlier or later step. - For more information, refer to :meth:`.Sphinx.add_css_file()`. + For more information, refer to :meth:`.Sphinx.add_css_file`. .. versionadded:: 1.8 .. versionchanged:: 3.5 @@ -1641,7 +1641,7 @@ and also make use of these options. As a special attribute, *priority* can be set as an integer to load the JavaScript file at an earlier or later step. - For more information, refer to :meth:`.Sphinx.add_js_file()`. + For more information, refer to :meth:`.Sphinx.add_js_file`. .. versionadded:: 1.8 .. versionchanged:: 3.5 @@ -2788,7 +2788,8 @@ These options influence LaTeX output. * :code-py:`'uplatex'` -- upLaTeX (default if :confval:`language` is :code-py:`'ja'`) - .. caution:: + .. important:: + ``'pdflatex'``\ 's support for Unicode characters is limited. If your project uses Unicode characters, setting the engine to ``'xelatex'`` or ``'lualatex'`` @@ -2800,10 +2801,10 @@ These options influence LaTeX output. .. note:: - Sphinx 2.0 adds support to ``'pdflatex'`` in Latin language document of - occasional Cyrillic or Greek letters or words. - This is not automatic, see the discussion - of the ``'fontenc'`` key in :confval:`latex_elements` . + Sphinx 2.0 adds support for occasional Cyrillic and Greek letters or + words in documents using a Latin language and ``'pdflatex'``. To enable + this, the :ref:`fontenc` key of :ref:`latex_elements + ` must be used appropriately. .. note:: @@ -2813,23 +2814,24 @@ These options influence LaTeX output. the only comprehensive solution (as far as we know) is to use ``'xelatex'`` or ``'lualatex'`` *and* to add ``r'\usepackage{unicode-math}'`` - (e.g. via the :confval:`latex_elements` ``'preamble'`` key). + (e.g. via the :ref:`preamble` key of :ref:`latex_elements + `). You may prefer ``r'\usepackage[math-style=literal]{unicode-math}'`` to keep a Unicode literal such as ``α`` (U+03B1) as-is in output, rather than being rendered as :math:`\alpha`. .. versionchanged:: 2.1.0 - Use ``xelatex`` (and LaTeX package ``xeCJK``) + Use ``'xelatex'`` (and LaTeX package ``xeCJK``) by default for Chinese documents. .. versionchanged:: 2.2.1 - Use ``xelatex`` by default for Greek documents. + Use ``'xelatex'`` by default for Greek documents. .. versionchanged:: 2.3 - Add ``uplatex`` support. + Add ``'uplatex'`` support. .. versionchanged:: 4.0 - Use ``uplatex`` by default for Japanese documents. + Use ``'uplatex'`` by default for Japanese documents. .. confval:: latex_documents :type: :code-py:`Sequence[tuple[str, str, str, str, str, bool]]` @@ -2899,16 +2901,16 @@ These options influence LaTeX output. :type: :code-py:`'part' | 'chapter' | 'section'` :default: :code-py:`None` - This value determines the topmost sectioning unit. - By default, the topmost sectioning unit is switched by documentclass: - ``section`` is used if documentclass will be ``howto``, - otherwise ``chapter`` is used be used. + This value determines the topmost sectioning unit. The default setting is + ``'section'`` if :confval:`latex_theme` is ``'howto'``, and ``'chapter'`` + if it is ``'manual'``. The alternative in both cases is to specify + ``'part'``, which means that LaTeX document will use the :code-tex:`\\part` + command. - Note that if LaTeX uses :code-tex:`\\part` command, - then the numbering of sectioning units one level deep gets off-sync - with HTML numbering, - because LaTeX numbers :code-tex:`\\chapter` continuously - (or :code-tex:`\\section` for ``howto``). + In that case the numbering of sectioning units one level deep gets off-sync + with HTML numbering, as by default LaTeX does not reset + :code-tex:`\\chapter` numbering (or :code-tex:`\\section` for ``'howto'`` + theme) when encountering :code-tex:`\\part` command. .. versionadded:: 1.4 @@ -3107,7 +3109,7 @@ These options influence LaTeX output. Use Xindy_ to prepare the index of general terms. By default, the LaTeX builder uses :program:`makeindex` for preparing the index of general terms . - This means that words with UTF-8 characters will be + Using Xindy_ means that words with UTF-8 characters will be ordered correctly for the :confval:`language`. .. _Xindy: https://xindy.sourceforge.net/ @@ -3131,7 +3133,7 @@ These options influence LaTeX output. for using :code-py:`'pdflatex'` engine with Cyrillic scripts. With both :code-py:`'pdflatex'` and Unicode engines, Cyrillic documents handle the indexing of Latin names correctly, - even with diacritics. + even those having diacritics. .. versionadded:: 1.8 @@ -3167,12 +3169,9 @@ These options influence LaTeX output. A list of file names, relative to the :term:`configuration directory`, to copy to the build directory when building LaTeX output. This is useful to copy files that Sphinx doesn't copy automatically, - e.g. if they are referenced in custom LaTeX added in ``latex_elements``. + or to overwrite Sphinx LaTeX support files with custom versions. Image files that are referenced in source files (e.g. via ``.. image::``) - are copied automatically. - - You have to make sure yourself that the filenames don't collide with those - of any automatically copied files. + are copied automatically and should not be listed there. .. attention:: Filenames with the ``.tex`` extension will be automatically diff --git a/doc/usage/restructuredtext/directives.rst b/doc/usage/restructuredtext/directives.rst index 713748971e3..945a6a877d3 100644 --- a/doc/usage/restructuredtext/directives.rst +++ b/doc/usage/restructuredtext/directives.rst @@ -840,7 +840,7 @@ __ https://pygments.org/docs/lexers Strip indentation characters from the code block. When number given, leading N characters are removed. When no argument given, leading spaces - are removed via :func:`textwrap.dedent()`. For example:: + are removed via :func:`textwrap.dedent`. For example:: .. code-block:: ruby :linenos: diff --git a/pyproject.toml b/pyproject.toml index dcca55027f8..93a3dd405ea 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -87,7 +87,7 @@ lint = [ "types-colorama==0.4.15.20240311", "types-defusedxml==0.7.0.20240218", "types-docutils==0.21.0.20240724", - "types-Pillow==10.2.0.20240520", + "types-Pillow==10.2.0.20240822", "types-Pygments==2.18.0.20240506", "types-requests>=2.30.0", # align with requests "tomli>=2", # for mypy (Python<=3.10) @@ -135,7 +135,7 @@ exclude = [ ] [tool.mypy] -files = ["sphinx", "utils", "tests"] +files = ["sphinx", "utils", "tests", "doc/conf.py"] exclude = [ "tests/roots", # tests/ @@ -196,22 +196,12 @@ exclude = [ "^tests/test_util/typing_test_data\\.py$", # tests/test_writers ] -check_untyped_defs = true python_version = "3.10" +strict = true show_column_numbers = true show_error_context = true -strict_optional = true -warn_redundant_casts = true -warn_unused_configs = true -warn_unused_ignores = true -disallow_any_generics = true -disallow_incomplete_defs = true -disallow_subclassing_any = true -disallow_untyped_calls = true -disallow_untyped_decorators = true -disallow_untyped_defs = true -no_implicit_reexport = true -extra_checks = true +strict_equality = false +warn_return_any = false enable_error_code = [ "type-arg", "redundant-self", diff --git a/sphinx/builders/latex/constants.py b/sphinx/builders/latex/constants.py index 9da66e82698..4da2de36f38 100644 --- a/sphinx/builders/latex/constants.py +++ b/sphinx/builders/latex/constants.py @@ -49,7 +49,7 @@ BoldFont = *Bold, BoldItalicFont = *BoldOblique, ] -\setmonofont{FreeMono}[ +\setmonofont{FreeMono}[Scale=0.9, Extension = .otf, UprightFont = *, ItalicFont = *Oblique, @@ -142,7 +142,6 @@ 'fontenc': ('\\usepackage{fontspec}\n' '\\defaultfontfeatures[\\rmfamily,\\sffamily,\\ttfamily]{}'), 'fontpkg': XELATEX_DEFAULT_FONTPKG, - 'fvset': '\\fvset{fontsize=\\small}', 'fontsubstitution': '', 'textgreek': '', 'utf8extra': ('\\catcode`^^^^00a0\\active\\protected\\def^^^^00a0' @@ -155,7 +154,6 @@ 'fontenc': ('\\usepackage{fontspec}\n' '\\defaultfontfeatures[\\rmfamily,\\sffamily,\\ttfamily]{}'), 'fontpkg': LUALATEX_DEFAULT_FONTPKG, - 'fvset': '\\fvset{fontsize=\\small}', 'fontsubstitution': '', 'textgreek': '', 'utf8extra': ('\\catcode`^^^^00a0\\active\\protected\\def^^^^00a0' diff --git a/sphinx/domains/_index.py b/sphinx/domains/_index.py index 1598d2f2026..1b651c5b4da 100644 --- a/sphinx/domains/_index.py +++ b/sphinx/domains/_index.py @@ -14,12 +14,41 @@ class IndexEntry(NamedTuple): + """ + An index entry. + + .. note:: + + The *qualifier* and *description* are not rendered for some output formats, + such as LaTeX. + """ + + #: The name of the index entry to be displayed. name: str + + #: The sub-entry related type. One of: + #: + #: ``0`` + #: A normal entry. + #: ``1`` + #: An entry with sub-entries. + #: ``2`` + #: A sub-entry. subtype: int + + #: *docname* where the entry is located. docname: str + + #: Anchor for the entry within `docname` anchor: str + + #: Extra info for the entry. extra: str + + #: Qualifier for the description. qualifier: str + + #: Description for the entry. descr: str @@ -75,39 +104,7 @@ def generate( ``content``: A sequence of ``(letter, entries)`` tuples, where ``letter`` is the "heading" for the given ``entries``, usually the starting letter, and - ``entries`` is a sequence of single entries. Each entry is a sequence - ``[name, subtype, docname, anchor, extra, qualifier, descr]``. The - items in this sequence have the following meaning: - - ``name`` - The name of the index entry to be displayed. - - ``subtype`` - The sub-entry related type. One of: - - ``0`` - A normal entry. - ``1`` - An entry with sub-entries. - ``2`` - A sub-entry. - - ``docname`` - *docname* where the entry is located. - - ``anchor`` - Anchor for the entry within ``docname`` - - ``extra`` - Extra info for the entry. - - ``qualifier`` - Qualifier for the description. - - ``descr`` - Description for the entry. - - Qualifier and description are not rendered for some output formats such - as LaTeX. + ``entries`` is a sequence of single entries. + Each entry is an :py:class:`IndexEntry`. """ raise NotImplementedError diff --git a/sphinx/ext/autodoc/__init__.py b/sphinx/ext/autodoc/__init__.py index 28559e0eccc..63ec1a0e8f8 100644 --- a/sphinx/ext/autodoc/__init__.py +++ b/sphinx/ext/autodoc/__init__.py @@ -177,7 +177,7 @@ def merge_members_option(options: dict) -> None: # Some useful event listener factories for autodoc-process-docstring. -def cut_lines(pre: int, post: int = 0, what: str | None = None) -> Callable: +def cut_lines(pre: int, post: int = 0, what: str | list[str] | None = None) -> Callable: """Return a listener that removes the first *pre* and last *post* lines of every docstring. If *what* is a sequence of strings, only docstrings of a type in *what* will be processed. diff --git a/sphinx/ext/intersphinx/_load.py b/sphinx/ext/intersphinx/_load.py index 1973de379be..358ae1f7ccb 100644 --- a/sphinx/ext/intersphinx/_load.py +++ b/sphinx/ext/intersphinx/_load.py @@ -211,7 +211,10 @@ def _fetch_inventory_group( for location in project.locations: # location is either None or a non-empty string - inv = f'{project.target_uri}/{INVENTORY_FILENAME}' if location is None else location + if location is None: + inv = posixpath.join(project.target_uri, INVENTORY_FILENAME) + else: + inv = location # decide whether the inventory must be read: always read local # files; remote ones only if the cache time is expired diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py index 0df58b52d4f..5436900db12 100644 --- a/sphinx/jinja2glue.py +++ b/sphinx/jinja2glue.py @@ -118,7 +118,7 @@ class SphinxFileSystemLoader(FileSystemLoader): def get_source( self, environment: Environment, template: str - ) -> tuple[str, str, Callable]: + ) -> tuple[str, str, Callable[[], bool]]: for searchpath in self.searchpath: filename = path.join(searchpath, template) f = open_if_exists(filename) @@ -224,7 +224,7 @@ def _newest_template_mtime_name(self) -> tuple[float, str]: def get_source( self, environment: Environment, template: str - ) -> tuple[str, str, Callable]: + ) -> tuple[str, str, Callable[[], bool]]: loaders = self.loaders # exclamation mark starts search from theme if template.startswith('!'): diff --git a/sphinx/texinputs/sphinxlatexstyleheadings.sty b/sphinx/texinputs/sphinxlatexstyleheadings.sty index e9121996b42..08773c0b658 100644 --- a/sphinx/texinputs/sphinxlatexstyleheadings.sty +++ b/sphinx/texinputs/sphinxlatexstyleheadings.sty @@ -4,6 +4,12 @@ \ProvidesPackage{sphinxlatexstyleheadings}[2023/02/11 headings] \RequirePackage[nobottomtitles*]{titlesec} +% tests showed that this setting guarantees \section title has +% 3 lines of text following it on same page if near bottom. +\renewcommand\bottomtitlespace{6\baselineskip} +% the default setting of 0.2\textheight is about 11\baselineskip +% (for 10pt letterpaper documents) and may create large voids. + \@ifpackagelater{titlesec}{2016/03/15}% {\@ifpackagelater{titlesec}{2016/03/21}% {}% @@ -47,7 +53,6 @@ \titleformat{\subparagraph}{\normalsize\py@HeaderFamily}% {\py@TitleColor\thesubparagraph}{0.5em}{\py@TitleColor} - % Since Sphinx 1.5, users should use HeaderFamily key to 'sphinxsetup' rather % than defining their own \py@HeaderFamily command (which is still possible). % Memo: \py@HeaderFamily is also used by \maketitle as defined in diff --git a/sphinx/util/template.py b/sphinx/util/template.py index 2b38e3a8678..1cfc287a821 100644 --- a/sphinx/util/template.py +++ b/sphinx/util/template.py @@ -124,7 +124,11 @@ def __init__(self, confdir: str | os.PathLike[str], self.loaders.append(loader) self.sysloaders.append(loader) - def get_source(self, environment: Environment, template: str) -> tuple[str, str, Callable]: + def get_source( + self, + environment: Environment, + template: str, + ) -> tuple[str, str, Callable[[], bool]]: if template.startswith('!'): # search a template from ``system_templates_paths`` loaders = self.sysloaders diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py index 0f2ffc29f0f..00e8db942a2 100644 --- a/sphinx/writers/latex.py +++ b/sphinx/writers/latex.py @@ -758,26 +758,30 @@ def has_multi_line(e: Element) -> bool: if multi_tp_list: if multi_arglist: - self.body.append(CR + r'\pysigwithonelineperargwithonelinepertparg{') + self.body.append(CR + r'\pysigwithonelineperargwithonelinepertparg' + + CR + '{') else: - self.body.append(CR + r'\pysiglinewithargsretwithonelinepertparg{') + self.body.append(CR + r'\pysiglinewithargsretwithonelinepertparg' + + CR + '{') else: if multi_arglist: - self.body.append(CR + r'\pysigwithonelineperargwithtypelist{') + self.body.append(CR + r'\pysigwithonelineperargwithtypelist' + + CR + '{') else: - self.body.append(CR + r'\pysiglinewithargsretwithtypelist{') + self.body.append(CR + r'\pysiglinewithargsretwithtypelist' + + CR + '{') break if isinstance(child, addnodes.desc_parameterlist): # arglist only: \macro{name}{arglist}{retann} if has_multi_line(child): - self.body.append(CR + r'\pysigwithonelineperarg{') + self.body.append(CR + r'\pysigwithonelineperarg' + CR + '{') else: - self.body.append(CR + r'\pysiglinewithargsret{') + self.body.append(CR + r'\pysiglinewithargsret' + CR + '{') break else: # no tp_list, no arglist: \macro{name} - self.body.append(CR + r'\pysigline{') + self.body.append(CR + r'\pysigline' + CR + '{') def _depart_signature_line(self, node: Element) -> None: self.body.append('}') @@ -878,26 +882,32 @@ def visit_desc_parameterlist(self, node: Element) -> None: if self.has_tp_list: if self.orphan_tp_list: # close type parameters list (#2) - self.body.append('}{') + self.body.append('}' + CR + '{') # empty parameters list argument (#3) return else: # close name argument (#1), open parameters list argument (#2) - self.body.append('}{') + self.body.append('}' + CR + '{') self._visit_sig_parameter_list(node, addnodes.desc_parameter) def depart_desc_parameterlist(self, node: Element) -> None: # close parameterlist, open return annotation - self.body.append('}{') + assert not self.orphan_tp_list + self.body.append('}' + CR + '{') def visit_desc_type_parameter_list(self, node: Element) -> None: # close name argument (#1), open type parameters list argument (#2) - self.body.append('}{') + self.body.append('}' + CR + '{') self._visit_sig_parameter_list(node, addnodes.desc_type_parameter) def depart_desc_type_parameter_list(self, node: Element) -> None: - # close type parameters list, open parameters list argument (#3) - self.body.append('}{') + if self.orphan_tp_list: + # this node next sibling isn't a desc_parameterlist, there are no parameters: + # close the type list, output an empty parameter list, open return annotation. + self.body.append('}' + CR + '{}' + CR + '{') + else: + # close type parameters list, open parameters list argument (#3) + self.body.append('}' + CR + '{') def _visit_sig_parameter(self, node: Element, parameter_macro: str) -> None: if self.is_first_param: diff --git a/tests/test_application.py b/tests/test_application.py index f8676ddfedf..c4b11b64127 100644 --- a/tests/test_application.py +++ b/tests/test_application.py @@ -25,7 +25,6 @@ def test_instantiation( tmp_path_factory: pytest.TempPathFactory, rootdir: str | os.PathLike[str] | None, - monkeypatch: pytest.MonkeyPatch, ) -> None: # Given src_dir = tmp_path_factory.getbasetemp() / 'root' diff --git a/tests/test_builders/test_build_latex.py b/tests/test_builders/test_build_latex.py index 2aa4e0ea565..ea6dc7475ca 100644 --- a/tests/test_builders/test_build_latex.py +++ b/tests/test_builders/test_build_latex.py @@ -2184,10 +2184,6 @@ def test_duplicated_labels_before_module(app): app.build() content: str = (app.outdir / 'projectnamenotset.tex').read_text(encoding='utf8') - def count_label(name): - text = r'\phantomsection\label{\detokenize{%s}}' % name - return content.count(text) - pattern = ( r'\\phantomsection\\label\{\\detokenize\{index:label-(?:auto-)?\d+[a-z]*}}' ) @@ -2230,43 +2226,71 @@ def test_one_parameter_per_line(app): # TODO: should these asserts check presence or absence of a final \sphinxparamcomma? # signature of 23 characters is too short to trigger one-param-per-line mark-up - assert '\\pysiglinewithargsret{\\sphinxbfcode{\\sphinxupquote{hello}}}' in result + assert ( + '\\pysiglinewithargsret\n' + '{\\sphinxbfcode{\\sphinxupquote{hello}}}\n' + '{\\sphinxparam{' in result + ) - assert '\\pysigwithonelineperarg{\\sphinxbfcode{\\sphinxupquote{foo}}}' in result + assert ( + '\\pysigwithonelineperarg\n' + '{\\sphinxbfcode{\\sphinxupquote{foo}}}\n' + '{\\sphinxoptional{\\sphinxparam{' in result + ) # generic_arg[T] assert ( - '\\pysiglinewithargsretwithtypelist{\\sphinxbfcode{\\sphinxupquote{generic\\_arg}}}' - '{\\sphinxtypeparam{\\DUrole{n}{T}}}{}{}' - ) in result + '\\pysiglinewithargsretwithtypelist\n' + '{\\sphinxbfcode{\\sphinxupquote{generic\\_arg}}}\n' + '{\\sphinxtypeparam{\\DUrole{n}{T}}}\n' + '{}\n' + '{}\n' in result + ) # generic_foo[T]() assert ( - '\\pysiglinewithargsretwithtypelist{\\sphinxbfcode{\\sphinxupquote{generic\\_foo}}}' - ) in result + '\\pysiglinewithargsretwithtypelist\n' + '{\\sphinxbfcode{\\sphinxupquote{generic\\_foo}}}\n' + '{\\sphinxtypeparam{\\DUrole{n}{T}}}\n' + '{}\n' + '{}\n' in result + ) # generic_bar[T](x: list[T]) assert ( - '\\pysigwithonelineperargwithtypelist{\\sphinxbfcode{\\sphinxupquote{generic\\_bar}}}' - ) in result + '\\pysigwithonelineperargwithtypelist\n' + '{\\sphinxbfcode{\\sphinxupquote{generic\\_bar}}}\n' + '{\\sphinxtypeparam{' in result + ) # generic_ret[R]() -> R assert ( - '\\pysiglinewithargsretwithtypelist{\\sphinxbfcode{\\sphinxupquote{generic\\_ret}}}' - '{\\sphinxtypeparam{\\DUrole{n}{R}}}{}{{ $\\rightarrow$ R}}' - ) in result + '\\pysiglinewithargsretwithtypelist\n' + '{\\sphinxbfcode{\\sphinxupquote{generic\\_ret}}}\n' + '{\\sphinxtypeparam{\\DUrole{n}{R}}}\n' + '{}\n' + '{{ $\\rightarrow$ R}}\n' in result + ) # MyGenericClass[X] assert ( - '\\pysiglinewithargsretwithtypelist{\\sphinxbfcode{\\sphinxupquote{class\\DUrole{w}{ ' - '}}}\\sphinxbfcode{\\sphinxupquote{MyGenericClass}}}' - ) in result + '\\pysiglinewithargsretwithtypelist\n' + '{\\sphinxbfcode{\\sphinxupquote{class\\DUrole{w}{ }}}' + '\\sphinxbfcode{\\sphinxupquote{MyGenericClass}}}\n' + '{\\sphinxtypeparam{\\DUrole{n}{X}}}\n' + '{}\n' + '{}\n' in result + ) # MyList[T](list[T]) assert ( - '\\pysiglinewithargsretwithtypelist{\\sphinxbfcode{\\sphinxupquote{class\\DUrole{w}{ ' - '}}}\\sphinxbfcode{\\sphinxupquote{MyList}}}' - ) in result + '\\pysiglinewithargsretwithtypelist\n' + '{\\sphinxbfcode{\\sphinxupquote{class\\DUrole{w}{ }}}' + '\\sphinxbfcode{\\sphinxupquote{MyList}}}\n' + '{\\sphinxtypeparam{\\DUrole{n}{T}}}\n' + '{\\sphinxparam{list{[}T{]}}}\n' + '{}\n' in result + ) @pytest.mark.sphinx('latex', testroot='markup-rubric') diff --git a/tests/test_builders/test_build_texinfo.py b/tests/test_builders/test_build_texinfo.py index 9b05857b52c..e77306c3c52 100644 --- a/tests/test_builders/test_build_texinfo.py +++ b/tests/test_builders/test_build_texinfo.py @@ -34,7 +34,7 @@ def test_texinfo(app): except CalledProcessError as exc: print(exc.stdout) print(exc.stderr) - msg = f'makeinfo exited with return code {exc.retcode}' + msg = f'makeinfo exited with return code {exc.returncode}' raise AssertionError(msg) from exc diff --git a/tests/test_config/test_config.py b/tests/test_config/test_config.py index 71599837564..7f748f11e70 100644 --- a/tests/test_config/test_config.py +++ b/tests/test_config/test_config.py @@ -762,7 +762,7 @@ def source_date_year(request, monkeypatch): @pytest.mark.sphinx('html', testroot='copyright-multiline') -def test_multi_line_copyright(source_date_year, app, monkeypatch): +def test_multi_line_copyright(source_date_year, app): app.build(force_all=True) content = (app.outdir / 'index.html').read_text(encoding='utf-8') diff --git a/tests/test_extensions/test_ext_apidoc.py b/tests/test_extensions/test_ext_apidoc.py index 0aefc1a7bdb..845405a9edb 100644 --- a/tests/test_extensions/test_ext_apidoc.py +++ b/tests/test_extensions/test_ext_apidoc.py @@ -302,7 +302,7 @@ def test_multibyte_parameters(make_app, apidoc): coderoot='test-root', options=['--ext-mathjax'], ) -def test_extension_parsed(make_app, apidoc): +def test_extension_parsed(apidoc): outdir = apidoc.outdir assert (outdir / 'conf.py').is_file() @@ -315,7 +315,7 @@ def test_extension_parsed(make_app, apidoc): coderoot='test-apidoc-toc/mypackage', options=['--implicit-namespaces'], ) -def test_toc_all_references_should_exist_pep420_enabled(make_app, apidoc): +def test_toc_all_references_should_exist_pep420_enabled(apidoc): """All references in toc should exist. This test doesn't say if directories with empty __init__.py and and nothing else should be skipped, just ensures consistency between what's referenced in the toc @@ -346,7 +346,7 @@ def test_toc_all_references_should_exist_pep420_enabled(make_app, apidoc): @pytest.mark.apidoc( coderoot='test-apidoc-toc/mypackage', ) -def test_toc_all_references_should_exist_pep420_disabled(make_app, apidoc): +def test_toc_all_references_should_exist_pep420_disabled(apidoc): """All references in toc should exist. This test doesn't say if directories with empty __init__.py and and nothing else should be skipped, just ensures consistency between what's referenced in the toc @@ -394,7 +394,7 @@ def extract_toc(path): coderoot='test-apidoc-subpackage-in-toc', options=['--separate'], ) -def test_subpackage_in_toc(make_app, apidoc): +def test_subpackage_in_toc(apidoc): """Make sure that empty subpackages with non-empty subpackages in them are not skipped (issue #4520) """ diff --git a/tests/test_extensions/test_ext_intersphinx.py b/tests/test_extensions/test_ext_intersphinx.py index c41ac982ce5..99dde92a57f 100644 --- a/tests/test_extensions/test_ext_intersphinx.py +++ b/tests/test_extensions/test_ext_intersphinx.py @@ -12,6 +12,7 @@ from sphinx import addnodes from sphinx.builders.html import INVENTORY_FILENAME +from sphinx.config import Config from sphinx.errors import ConfigError from sphinx.ext.intersphinx import ( inspect_main, @@ -768,3 +769,73 @@ def test_intersphinx_cache_limit(app): config=app.config, srcdir=app.srcdir, ) + + +def test_intersphinx_fetch_inventory_group_url(): + class InventoryHandler(http.server.BaseHTTPRequestHandler): + def do_GET(self): + self.send_response(200, 'OK') + self.end_headers() + self.wfile.write(INVENTORY_V2) + + def log_message(*args, **kwargs): + # Silenced. + pass + + with http_server(InventoryHandler) as server: + url1 = f'http://localhost:{server.server_port}' + url2 = f'http://localhost:{server.server_port}/' + + config = Config() + config.intersphinx_cache_limit = -1 + config.intersphinx_mapping = { + '1': (url1, None), + '2': (url2, None), + } + + now = int(time.time()) + # we can use 'srcdir=None' since we are raising in _fetch_inventory + kwds = {'cache': {}, 'now': now, 'config': config, 'srcdir': None} + # We need an exception with its 'args' attribute set (see error + # handling in sphinx.ext.intersphinx._load._fetch_inventory_group). + side_effect = ValueError('') + + project1 = _IntersphinxProject( + name='1', target_uri=url1, locations=(url1, None) + ) + with mock.patch( + 'sphinx.ext.intersphinx._load._fetch_inventory', side_effect=side_effect + ) as mockfn: + assert not _fetch_inventory_group(project=project1, **kwds) + mockfn.assert_any_call( + target_uri=url1, + inv_location=url1, + config=config, + srcdir=None, + ) + mockfn.assert_any_call( + target_uri=url1, + inv_location=url1 + '/' + INVENTORY_FILENAME, + config=config, + srcdir=None, + ) + + project2 = _IntersphinxProject( + name='2', target_uri=url2, locations=(url2, None) + ) + with mock.patch( + 'sphinx.ext.intersphinx._load._fetch_inventory', side_effect=side_effect + ) as mockfn: + assert not _fetch_inventory_group(project=project2, **kwds) + mockfn.assert_any_call( + target_uri=url2, + inv_location=url2, + config=config, + srcdir=None, + ) + mockfn.assert_any_call( + target_uri=url2, + inv_location=url2 + INVENTORY_FILENAME, + config=config, + srcdir=None, + ) diff --git a/tests/test_intl/test_intl.py b/tests/test_intl/test_intl.py index 29e3747bfa5..6f343e03dcb 100644 --- a/tests/test_intl/test_intl.py +++ b/tests/test_intl/test_intl.py @@ -809,9 +809,7 @@ def sleep(self, ds: float) -> None: @pytest.fixture -def mock_time_and_i18n( - monkeypatch: pytest.MonkeyPatch, -) -> tuple[pytest.MonkeyPatch, _MockClock]: +def mock_time_and_i18n() -> tuple[pytest.MonkeyPatch, _MockClock]: from sphinx.util.i18n import CatalogInfo # save the 'original' definition diff --git a/tests/test_util/test_util_i18n.py b/tests/test_util/test_util_i18n.py index 08c3ce0a3c0..5f0f3816540 100644 --- a/tests/test_util/test_util_i18n.py +++ b/tests/test_util/test_util_i18n.py @@ -179,13 +179,13 @@ def test_CatalogRepository(tmp_path): assert sorted(c.domain for c in repo.catalogs) == [] # no languages - repo = i18n.CatalogRepository(tmp_path, ['loc1', 'loc2'], None, 'utf-8') + repo = i18n.CatalogRepository(tmp_path, ['loc1', 'loc2'], '', 'utf-8') assert sorted(c.domain for c in repo.catalogs) == [] # unknown locale_dirs - repo = i18n.CatalogRepository(tmp_path, ['loc3'], None, 'utf-8') + repo = i18n.CatalogRepository(tmp_path, ['loc3'], '', 'utf-8') assert sorted(c.domain for c in repo.catalogs) == [] # no locale_dirs - repo = i18n.CatalogRepository(tmp_path, [], None, 'utf-8') + repo = i18n.CatalogRepository(tmp_path, [], '', 'utf-8') assert sorted(c.domain for c in repo.catalogs) == [] diff --git a/tests/test_util/test_util_rst.py b/tests/test_util/test_util_rst.py index e91fc24a789..bbe34f54b04 100644 --- a/tests/test_util/test_util_rst.py +++ b/tests/test_util/test_util_rst.py @@ -1,6 +1,5 @@ """Tests sphinx.util.rst functions.""" -import pytest from docutils.statemachine import StringList from jinja2 import Environment @@ -14,8 +13,7 @@ def test_escape(): assert escape('.. toctree::') == r'\.. toctree\:\:' -@pytest.mark.sphinx('html', testroot='root') -def test_append_epilog(app): +def test_append_epilog(): epilog = 'this is rst_epilog\ngood-bye reST!' content = StringList( ['hello Sphinx world', 'Sphinx is a document generator'], @@ -32,8 +30,7 @@ def test_append_epilog(app): ] -@pytest.mark.sphinx('html', testroot='root') -def test_prepend_prolog(app): +def test_prepend_prolog(): prolog = 'this is rst_prolog\nhello reST!' content = StringList( [ @@ -60,8 +57,7 @@ def test_prepend_prolog(app): ] -@pytest.mark.sphinx('html', testroot='root') -def test_prepend_prolog_with_CR(app): +def test_prepend_prolog_with_CR(): # prolog having CR at tail prolog = 'this is rst_prolog\nhello reST!\n' content = StringList( @@ -79,8 +75,7 @@ def test_prepend_prolog_with_CR(app): ] -@pytest.mark.sphinx('html', testroot='root') -def test_prepend_prolog_without_CR(app): +def test_prepend_prolog_without_CR(): # prolog not having CR at tail prolog = 'this is rst_prolog\nhello reST!' content = StringList( @@ -98,8 +93,7 @@ def test_prepend_prolog_without_CR(app): ] -@pytest.mark.sphinx('html', testroot='root') -def test_prepend_prolog_with_roles_in_sections(app): +def test_prepend_prolog_with_roles_in_sections(): prolog = 'this is rst_prolog\nhello reST!' content = StringList( [ @@ -130,8 +124,7 @@ def test_prepend_prolog_with_roles_in_sections(app): ] -@pytest.mark.sphinx('html', testroot='root') -def test_prepend_prolog_with_roles_in_sections_with_newline(app): +def test_prepend_prolog_with_roles_in_sections_with_newline(): # prologue with trailing line break prolog = 'this is rst_prolog\nhello reST!\n' content = StringList([':mod:`foo`', '-' * 10, '', 'hello'], 'dummy.rst') @@ -148,8 +141,7 @@ def test_prepend_prolog_with_roles_in_sections_with_newline(app): ] -@pytest.mark.sphinx('html', testroot='root') -def test_prepend_prolog_with_roles_in_sections_without_newline(app): +def test_prepend_prolog_with_roles_in_sections_without_newline(): # prologue with no trailing line break prolog = 'this is rst_prolog\nhello reST!' content = StringList([':mod:`foo`', '-' * 10, '', 'hello'], 'dummy.rst')