Sphinx 8.0.2__py3-none-any.whl → 8.1.0__py3-none-any.whl

sphinx/config.py

@@ -23,7 +23,7 @@ else:
 
 if TYPE_CHECKING:
     import os
-    from collections.abc import Collection, Iterator, Sequence, Set
+    from collections.abc import Collection, Iterable, Iterator, Sequence, Set
     from typing import TypeAlias
 
     from sphinx.application import Sphinx
@@ -271,7 +271,7 @@ class Config:
         'smartquotes': _Opt(True, 'env', ()),
         'smartquotes_action': _Opt('qDe', 'env', ()),
         'smartquotes_excludes': _Opt(
-            {'languages': ['ja'], 'builders': ['man', 'text']}, 'env', ()),
+            {'languages': ['ja', 'zh_CN', 'zh_TW'], 'builders': ['man', 'text']}, 'env', ()),
         'option_emphasise_placeholders': _Opt(False, 'env', ()),
     }
 
@@ -619,28 +619,55 @@ def init_numfig_format(app: Sphinx, config: Config) -> None:
     config.numfig_format = numfig_format
 
 
+def evaluate_copyright_placeholders(_app: Sphinx, config: Config) -> None:
+    """Replace copyright year placeholders (%Y) with the current year."""
+    replace_yr = str(time.localtime().tm_year)
+    for k in ('copyright', 'epub_copyright'):
+        if k in config:
+            value: str | Sequence[str] = config[k]
+            if isinstance(value, str):
+                if '%Y' in value:
+                    config[k] = value.replace('%Y', replace_yr)
+            else:
+                if any('%Y' in line for line in value):
+                    items = (line.replace('%Y', replace_yr) for line in value)
+                    config[k] = type(value)(items)  # type: ignore[call-arg]
+
+
 def correct_copyright_year(_app: Sphinx, config: Config) -> None:
     """Correct values of copyright year that are not coherent with
     the SOURCE_DATE_EPOCH environment variable (if set)
 
     See https://reproducible-builds.org/specs/source-date-epoch/
     """
-    if (source_date_epoch := getenv('SOURCE_DATE_EPOCH')) is None:
+    if source_date_epoch := int(getenv('SOURCE_DATE_EPOCH', '0')):
+        source_date_epoch_year = time.gmtime(source_date_epoch).tm_year
+    else:
         return
 
-    source_date_epoch_year = str(time.gmtime(int(source_date_epoch)).tm_year)
+    # If the current year is the replacement year, there's no work to do.
+    # We also skip replacement years that are in the future.
+    current_year = time.localtime().tm_year
+    if current_year <= source_date_epoch_year:
+        return
 
+    current_yr = str(current_year)
+    replace_yr = str(source_date_epoch_year)
     for k in ('copyright', 'epub_copyright'):
         if k in config:
             value: str | Sequence[str] = config[k]
             if isinstance(value, str):
-                config[k] = _substitute_copyright_year(value, source_date_epoch_year)
+                config[k] = _substitute_copyright_year(value, current_yr, replace_yr)
             else:
-                items = (_substitute_copyright_year(x, source_date_epoch_year) for x in value)
+                items = (
+                    _substitute_copyright_year(x, current_yr, replace_yr) for x in value
+                )
                 config[k] = type(value)(items)  # type: ignore[call-arg]
 
 
-def _substitute_copyright_year(copyright_line: str, replace_year: str) -> str:
+def _substitute_copyright_year(
+    copyright_line: str, current_year: str, replace_year: str
+) -> str:
     """Replace the year in a single copyright line.
 
     Legal formats are:
@@ -648,6 +675,7 @@ def _substitute_copyright_year(copyright_line: str, replace_year: str) -> str:
     * ``YYYY``
     * ``YYYY,``
     * ``YYYY ``
+    * ``YYYY-YYYY``
     * ``YYYY-YYYY,``
     * ``YYYY-YYYY ``
 
@@ -656,13 +684,17 @@ def _substitute_copyright_year(copyright_line: str, replace_year: str) -> str:
     if len(copyright_line) < 4 or not copyright_line[:4].isdigit():
         return copyright_line
 
-    if copyright_line[4:5] in {'', ' ', ','}:
+    if copyright_line[:4] == current_year and copyright_line[4:5] in {'', ' ', ','}:
         return replace_year + copyright_line[4:]
 
-    if copyright_line[4] != '-':
+    if copyright_line[4:5] != '-':
         return copyright_line
 
-    if copyright_line[5:9].isdigit() and copyright_line[9:10] in {'', ' ', ','}:
+    if (
+        copyright_line[5:9].isdigit()
+        and copyright_line[5:9] == current_year
+        and copyright_line[9:10] in {'', ' ', ','}
+    ):
         return copyright_line[:5] + replace_year + copyright_line[9:]
 
     return copyright_line
@@ -739,8 +771,8 @@ def check_primary_domain(app: Sphinx, config: Config) -> None:
         config.primary_domain = None
 
 
-def check_root_doc(app: Sphinx, env: BuildEnvironment, added: set[str],
-                   changed: set[str], removed: set[str]) -> set[str]:
+def check_root_doc(app: Sphinx, env: BuildEnvironment, added: Set[str],
+                   changed: Set[str], removed: Set[str]) -> Iterable[str]:
     """Adjust root_doc to 'contents' to support an old project which does not have
     any root_doc setting.
     """
@@ -758,6 +790,7 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect('config-inited', convert_source_suffix, priority=800)
     app.connect('config-inited', convert_highlight_options, priority=800)
     app.connect('config-inited', init_numfig_format, priority=800)
+    app.connect('config-inited', evaluate_copyright_placeholders, priority=795)
     app.connect('config-inited', correct_copyright_year, priority=800)
     app.connect('config-inited', check_confval_types, priority=800)
     app.connect('config-inited', check_primary_domain, priority=800)

sphinx/deprecation.py

@@ -40,7 +40,11 @@ def _deprecation_warning(
 
        # deprecated name -> (object to return, canonical path or empty string, removal version)
        _DEPRECATED_OBJECTS = {
-           'deprecated_name': (object_to_return, 'fully_qualified_replacement_name', (9, 0)),
+           'deprecated_name': (
+               object_to_return,
+               'fully_qualified_replacement_name',
+               (9, 0),
+           ),
        }
 
 
@@ -65,7 +69,9 @@ def _deprecation_warning(
 
     qualname = f'{module}.{attribute}'
     if canonical_name:
-        message = f'The alias {qualname!r} is deprecated, use {canonical_name!r} instead.'
+        message = (
+            f'The alias {qualname!r} is deprecated, use {canonical_name!r} instead.'
+        )
     else:
         message = f'{qualname!r} is deprecated.'
 

sphinx/directives/__init__.py

@@ -111,7 +111,9 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
         """
         raise ValueError
 
-    def add_target_and_index(self, name: ObjDescT, sig: str, signode: desc_signature) -> None:
+    def add_target_and_index(
+        self, name: ObjDescT, sig: str, signode: desc_signature
+    ) -> None:
         """
         Add cross-reference IDs and entries to self.indexnode, if applicable.
 
@@ -228,19 +230,18 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
             self.options['no-index'] = self.options['noindex']
         if 'no-index-entry' not in self.options and 'noindexentry' in self.options:
             self.options['no-index-entry'] = self.options['noindexentry']
-        if 'no-contents-entry' not in self.options and 'nocontentsentry' in self.options:
+        if (
+            'no-contents-entry' not in self.options
+            and 'nocontentsentry' in self.options
+        ):
             self.options['no-contents-entry'] = self.options['nocontentsentry']
 
-        node['no-index'] = node['noindex'] = no_index = (
-            'no-index' in self.options
-        )
-        node['no-index-entry'] = node['noindexentry'] = (
-            'no-index-entry' in self.options
-        )
+        node['no-index'] = node['noindex'] = no_index = 'no-index' in self.options
+        node['no-index-entry'] = node['noindexentry'] = 'no-index-entry' in self.options
         node['no-contents-entry'] = node['nocontentsentry'] = (
             'no-contents-entry' in self.options
         )
-        node['no-typesetting'] = ('no-typesetting' in self.options)
+        node['no-typesetting'] = 'no-typesetting' in self.options
         if self.domain:
             node['classes'].append(self.domain)
         node['classes'].append(node['objtype'])
@@ -287,8 +288,9 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
         content_node = addnodes.desc_content('', *content_children)
         node.append(content_node)
         self.transform_content(content_node)
-        self.env.app.emit('object-description-transform',
-                          self.domain, self.objtype, content_node)
+        self.env.app.emit(
+            'object-description-transform', self.domain, self.objtype, content_node
+        )
         DocFieldTransformer(self).transform_all(content_node)
         self.env.temp_data['object'] = None
         self.after_content()
@@ -299,8 +301,11 @@ class ObjectDescription(SphinxDirective, Generic[ObjDescT]):
             # If ``:no-index:`` is set, or there are no ids on the node
             # or any of its children, then just return the index node,
             # as Docutils expects a target node to have at least one id.
-            if node_ids := [node_id for el in node.findall(nodes.Element)  # type: ignore[var-annotated]
-                            for node_id in el.get('ids', ())]:
+            if node_ids := [  # type: ignore[var-annotated]
+                node_id
+                for el in node.findall(nodes.Element)
+                for node_id in el.get('ids', ())
+            ]:
                 target_node = nodes.target(ids=node_ids)
                 self.set_source_info(target_node)
                 return [self.indexnode, target_node]
@@ -321,16 +326,20 @@ class DefaultRole(SphinxDirective):
             docutils.unregister_role('')
             return []
         role_name = self.arguments[0]
-        role, messages = roles.role(role_name, self.state_machine.language,
-                                    self.lineno, self.state.reporter)
+        role, messages = roles.role(
+            role_name, self.state_machine.language, self.lineno, self.state.reporter
+        )
         if role:
             docutils.register_role('', role)  # type: ignore[arg-type]
             self.env.temp_data['default_role'] = role_name
         else:
             literal_block = nodes.literal_block(self.block_text, self.block_text)
             reporter = self.state.reporter
-            error = reporter.error('Unknown interpreted text role "%s".' % role_name,
-                                   literal_block, line=self.lineno)
+            error = reporter.error(
+                'Unknown interpreted text role "%s".' % role_name,
+                literal_block,
+                line=self.lineno,
+            )
             messages += [error]
 
         return cast(list[nodes.Node], messages)
@@ -351,7 +360,7 @@ class DefaultDomain(SphinxDirective):
         domain_name = self.arguments[0].lower()
         # if domain_name not in env.domains:
         #     # try searching by label
-        #     for domain in env.domains.values():
+        #     for domain in env.domains.sorted():
         #         if domain.label.lower() == domain_name:
         #             domain_name = domain.name
         #             break
@@ -360,7 +369,7 @@ class DefaultDomain(SphinxDirective):
 
 
 def setup(app: Sphinx) -> ExtensionMetadata:
-    app.add_config_value("strip_signature_backslash", False, 'env')
+    app.add_config_value('strip_signature_backslash', False, 'env')
     directives.register_directive('default-role', DefaultRole)
     directives.register_directive('default-domain', DefaultDomain)
     directives.register_directive('describe', ObjectDescription)

sphinx/directives/code.py

@@ -11,7 +11,8 @@ from docutils.parsers.rst import directives
 from sphinx import addnodes
 from sphinx.directives import optional_int
 from sphinx.locale import __
-from sphinx.util import logging, parselinenos
+from sphinx.util import logging
+from sphinx.util._lines import parse_line_num_spec
 from sphinx.util.docutils import SphinxDirective
 
 if TYPE_CHECKING:
@@ -45,13 +46,15 @@ class Highlight(SphinxDirective):
         force = 'force' in self.options
 
         self.env.temp_data['highlight_language'] = language
-        return [addnodes.highlightlang(lang=language,
-                                       force=force,
-                                       linenothreshold=linenothreshold)]
+        return [
+            addnodes.highlightlang(
+                lang=language, force=force, linenothreshold=linenothreshold
+            )
+        ]
 
 
 def dedent_lines(
-    lines: list[str], dedent: int | None, location: tuple[str, int] | None = None,
+    lines: list[str], dedent: int | None, location: tuple[str, int] | None = None
 ) -> list[str]:
     if dedent is None:
         return textwrap.dedent(''.join(lines)).splitlines(True)
@@ -70,10 +73,11 @@ def dedent_lines(
 
 
 def container_wrapper(
-    directive: SphinxDirective, literal_node: Node, caption: str,
+    directive: SphinxDirective, literal_node: Node, caption: str
 ) -> nodes.container:
-    container_node = nodes.container('', literal_block=True,
-                                     classes=['literal-block-wrapper'])
+    container_node = nodes.container(
+        '', literal_block=True, classes=['literal-block-wrapper']
+    )
     parsed = directive.parse_text_to_nodes(caption, offset=directive.content_offset)
     node = parsed[0]
     if isinstance(node, nodes.system_message):
@@ -119,11 +123,14 @@ class CodeBlock(SphinxDirective):
         if linespec:
             try:
                 nlines = len(self.content)
-                hl_lines = parselinenos(linespec, nlines)
+                hl_lines = parse_line_num_spec(linespec, nlines)
                 if any(i >= nlines for i in hl_lines):
-                    logger.warning(__('line number spec is out of range(1-%d): %r'),
-                                   nlines, self.options['emphasize-lines'],
-                                   location=location)
+                    logger.warning(
+                        __('line number spec is out of range(1-%d): %r'),
+                        nlines,
+                        self.options['emphasize-lines'],
+                        location=location,
+                    )
 
                 hl_lines = [x + 1 for x in hl_lines if x < nlines]
             except ValueError as err:
@@ -149,8 +156,9 @@ class CodeBlock(SphinxDirective):
             # no highlight language specified.  Then this directive refers the current
             # highlight setting via ``highlight`` directive or ``highlight_language``
             # configuration.
-            literal['language'] = self.env.temp_data.get('highlight_language',
-                                                         self.config.highlight_language)
+            literal['language'] = self.env.temp_data.get(
+                'highlight_language', self.config.highlight_language
+            )
         extra_args = literal['highlight_args'] = {}
         if hl_lines is not None:
             extra_args['hl_lines'] = hl_lines
@@ -200,11 +208,11 @@ class LiteralIncludeReader:
     def parse_options(self) -> None:
         for option1, option2 in self.INVALID_OPTIONS_PAIR:
             if option1 in self.options and option2 in self.options:
-                raise ValueError(__('Cannot use both "%s" and "%s" options') %
-                                 (option1, option2))
+                msg = __('Cannot use both "%s" and "%s" options') % (option1, option2)
+                raise ValueError(msg)
 
     def read_file(
-        self, filename: str, location: tuple[str, int] | None = None,
+        self, filename: str, location: tuple[str, int] | None = None
     ) -> list[str]:
         try:
             with open(filename, encoding=self.encoding, errors='strict') as f:
@@ -214,24 +222,28 @@ class LiteralIncludeReader:
 
                 return text.splitlines(True)
         except OSError as exc:
-            raise OSError(__('Include file %r not found or reading it failed') %
-                          filename) from exc
+            msg = __('Include file %r not found or reading it failed') % filename
+            raise OSError(msg) from exc
         except UnicodeError as exc:
-            raise UnicodeError(__('Encoding %r used for reading included file %r seems to '
-                                  'be wrong, try giving an :encoding: option') %
-                               (self.encoding, filename)) from exc
+            msg = __(
+                'Encoding %r used for reading included file %r seems to '
+                'be wrong, try giving an :encoding: option'
+            ) % (self.encoding, filename)
+            raise UnicodeError(msg) from exc
 
     def read(self, location: tuple[str, int] | None = None) -> tuple[str, int]:
         if 'diff' in self.options:
             lines = self.show_diff()
         else:
-            filters = [self.pyobject_filter,
-                       self.start_filter,
-                       self.end_filter,
-                       self.lines_filter,
-                       self.dedent_filter,
-                       self.prepend_filter,
-                       self.append_filter]
+            filters = [
+                self.pyobject_filter,
+                self.start_filter,
+                self.end_filter,
+                self.lines_filter,
+                self.dedent_filter,
+                self.prepend_filter,
+                self.append_filter,
+            ]
             lines = self.read_file(self.filename, location=location)
             for func in filters:
                 lines = func(lines, location=location)
@@ -246,33 +258,41 @@ class LiteralIncludeReader:
         return list(diff)
 
     def pyobject_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         pyobject = self.options.get('pyobject')
         if pyobject:
             from sphinx.pycode import ModuleAnalyzer
+
             analyzer = ModuleAnalyzer.for_file(self.filename, '')
             tags = analyzer.find_tags()
             if pyobject not in tags:
-                raise ValueError(__('Object named %r not found in include file %r') %
-                                 (pyobject, self.filename))
+                msg = __('Object named %r not found in include file %r') % (
+                    pyobject,
+                    self.filename,
+                )
+                raise ValueError(msg)
             start = tags[pyobject][1]
             end = tags[pyobject][2]
-            lines = lines[start - 1:end]
+            lines = lines[start - 1 : end]
             if 'lineno-match' in self.options:
                 self.lineno_start = start
 
         return lines
 
     def lines_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         linespec = self.options.get('lines')
         if linespec:
-            linelist = parselinenos(linespec, len(lines))
+            linelist = parse_line_num_spec(linespec, len(lines))
             if any(i >= len(lines) for i in linelist):
-                logger.warning(__('line number spec is out of range(1-%d): %r'),
-                               len(lines), linespec, location=location)
+                logger.warning(
+                    __('line number spec is out of range(1-%d): %r'),
+                    len(lines),
+                    linespec,
+                    location=location,
+                )
 
             if 'lineno-match' in self.options:
                 # make sure the line list is not "disjoint".
@@ -280,18 +300,21 @@ class LiteralIncludeReader:
                 if all(first + i == n for i, n in enumerate(linelist)):
                     self.lineno_start += linelist[0]
                 else:
-                    raise ValueError(__('Cannot use "lineno-match" with a disjoint '
-                                        'set of "lines"'))
+                    msg = __('Cannot use "lineno-match" with a disjoint set of "lines"')
+                    raise ValueError(msg)
 
             lines = [lines[n] for n in linelist if n < len(lines)]
             if not lines:
-                raise ValueError(__('Line spec %r: no lines pulled from include file %r') %
-                                 (linespec, self.filename))
+                msg = __('Line spec %r: no lines pulled from include file %r') % (
+                    linespec,
+                    self.filename,
+                )
+                raise ValueError(msg)
 
         return lines
 
     def start_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         if 'start-at' in self.options:
             start = self.options.get('start-at')
@@ -309,7 +332,7 @@ class LiteralIncludeReader:
                         if 'lineno-match' in self.options:
                             self.lineno_start += lineno + 1
 
-                        return lines[lineno + 1:]
+                        return lines[lineno + 1 :]
                     else:
                         if 'lineno-match' in self.options:
                             self.lineno_start += lineno
@@ -324,7 +347,7 @@ class LiteralIncludeReader:
         return lines
 
     def end_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         if 'end-at' in self.options:
             end = self.options.get('end-at')
@@ -339,7 +362,7 @@ class LiteralIncludeReader:
             for lineno, line in enumerate(lines):
                 if end in line:
                     if inclusive:
-                        return lines[:lineno + 1]
+                        return lines[: lineno + 1]
                     else:
                         if lineno == 0:
                             pass  # end-before ignores first line
@@ -353,7 +376,7 @@ class LiteralIncludeReader:
         return lines
 
     def prepend_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         prepend = self.options.get('prepend')
         if prepend:
@@ -362,7 +385,7 @@ class LiteralIncludeReader:
         return lines
 
     def append_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         append = self.options.get('append')
         if append:
@@ -371,7 +394,7 @@ class LiteralIncludeReader:
         return lines
 
     def dedent_filter(
-        self, lines: list[str], location: tuple[str, int] | None = None,
+        self, lines: list[str], location: tuple[str, int] | None = None
     ) -> list[str]:
         if 'dedent' in self.options:
             return dedent_lines(lines, self.options.get('dedent'), location=location)
@@ -417,8 +440,9 @@ class LiteralInclude(SphinxDirective):
     def run(self) -> list[Node]:
         document = self.state.document
         if not document.settings.file_insertion_enabled:
-            return [document.reporter.warning('File insertion disabled',
-                                              line=self.lineno)]
+            return [
+                document.reporter.warning('File insertion disabled', line=self.lineno)
+            ]
         # convert options['diff'] to absolute path
         if 'diff' in self.options:
             _, path = self.env.relfn2path(self.options['diff'])
@@ -439,17 +463,23 @@ class LiteralInclude(SphinxDirective):
                 retnode['language'] = 'udiff'
             elif 'language' in self.options:
                 retnode['language'] = self.options['language']
-            if ('linenos' in self.options or 'lineno-start' in self.options or
-                    'lineno-match' in self.options):
+            if (
+                'linenos' in self.options
+                or 'lineno-start' in self.options
+                or 'lineno-match' in self.options
+            ):
                 retnode['linenos'] = True
             retnode['classes'] += self.options.get('class', [])
             extra_args = retnode['highlight_args'] = {}
             if 'emphasize-lines' in self.options:
-                hl_lines = parselinenos(self.options['emphasize-lines'], lines)
+                hl_lines = parse_line_num_spec(self.options['emphasize-lines'], lines)
                 if any(i >= lines for i in hl_lines):
-                    logger.warning(__('line number spec is out of range(1-%d): %r'),
-                                   lines, self.options['emphasize-lines'],
-                                   location=location)
+                    logger.warning(
+                        __('line number spec is out of range(1-%d): %r'),
+                        lines,
+                        self.options['emphasize-lines'],
+                        location=location,
+                    )
                 extra_args['hl_lines'] = [x + 1 for x in hl_lines if x < lines]
             extra_args['linenostart'] = reader.lineno_start