Merge branch 'master' into master

Lynn-Hu-D · web-flow · commit 851968f649f0 · 2024-02-28T11:31:06.000-08:00
diff --git a/CHANGES.rst b/CHANGES.rst
@@ -33,6 +33,8 @@ Features added
 Bugs fixed
 ----------
 
+* #11944: Use anchor in search preview.
+  Patch by Will Lachance.
 * #11668: Raise a useful error when ``theme.conf`` is missing.
   Patch by Vinay Sajip.
 * #11622: Ensure that the order of keys in ``searchindex.js`` is deterministic.
diff --git a/doc/man/sphinx-build.rst b/doc/man/sphinx-build.rst
@@ -39,7 +39,11 @@ Options
    Extensions can add their own builders.
 
    .. important::
-      Sphinx only recognizes the ``-M`` option if it is used first.
+      Sphinx only recognizes the ``-M`` option if it is used first, along with
+      the source and output directories, before any other options are passed.
+      For example::
+
+          sphinx-build -M html ./source ./build -W --keep-going
 
    The *make-mode* provides the same build functionality as
    a default :ref:`Makefile or Make.bat <makefile_options>`,
diff --git a/pyproject.toml b/pyproject.toml
@@ -87,6 +87,7 @@ lint = [
     "sphinx-lint",
     "docutils-stubs",
     "types-requests",
+    "pytest>=6.0",
 ]
 test = [
     "pytest>=6.0",
@@ -133,9 +134,6 @@ exclude = [
 files = ["sphinx"]
 check_untyped_defs = true
 disallow_incomplete_defs = true
-follow_imports = "skip"
-ignore_missing_imports = true
-no_implicit_optional = true
 python_version = "3.9"
 show_column_numbers = true
 show_error_context = true
@@ -152,6 +150,9 @@ enable_error_code = [
     "ignore-without-code",
     "unused-awaitable",
 ]
+disable_error_code = [
+    "import-untyped",
+]
 
 [[tool.mypy.overrides]]
 module = [
diff --git a/sphinx/ext/autosummary/generate.py b/sphinx/ext/autosummary/generate.py
@@ -133,7 +133,8 @@ def __init__(self, app: Sphinx) -> None:
 
         if app.translator:
             self.env.add_extension("jinja2.ext.i18n")
-            self.env.install_gettext_translations(app.translator)
+            # ``install_gettext_translations`` is injected by the ``jinja2.ext.i18n`` extension
+            self.env.install_gettext_translations(app.translator)  # type: ignore[attr-defined]
 
     def render(self, template_name: str, context: dict) -> str:
         """Render a template file."""
diff --git a/sphinx/jinja2glue.py b/sphinx/jinja2glue.py
@@ -8,17 +8,12 @@
 
 from jinja2 import BaseLoader, FileSystemLoader, TemplateNotFound
 from jinja2.sandbox import SandboxedEnvironment
-from jinja2.utils import open_if_exists
+from jinja2.utils import open_if_exists, pass_context
 
 from sphinx.application import TemplateBridge
 from sphinx.util import logging
 from sphinx.util.osutil import mtimes_of_files
 
-try:
-    from jinja2.utils import pass_context
-except ImportError:
-    from jinja2 import contextfunction as pass_context
-
 if TYPE_CHECKING:
     from collections.abc import Iterator
 
@@ -194,7 +189,9 @@ def init(
         self.environment.globals['accesskey'] = pass_context(accesskey)
         self.environment.globals['idgen'] = idgen
         if use_i18n:
-            self.environment.install_gettext_translations(builder.app.translator)
+            # ``install_gettext_translations`` is injected by the ``jinja2.ext.i18n`` extension
+            self.environment.install_gettext_translations(  # type: ignore[attr-defined]
+                builder.app.translator)
 
     def render(self, template: str, context: dict) -> str:  # type: ignore[override]
         return self.environment.get_template(template).render(context)
@@ -218,5 +215,6 @@ def get_source(self, environment: Environment, template: str) -> tuple[str, str,
                 return loader.get_source(environment, template)
             except TemplateNotFound:
                 pass
-        msg = f"{template!r} not found in {self.environment.loader.pathchain}"
+        msg = (f"{template!r} not found in "
+               f"{self.environment.loader.pathchain}")  # type: ignore[union-attr]
         raise TemplateNotFound(msg)
diff --git a/sphinx/registry.py b/sphinx/registry.py
@@ -11,7 +11,7 @@
 if sys.version_info >= (3, 10):
     from importlib.metadata import entry_points
 else:
-    from importlib_metadata import entry_points
+    from importlib_metadata import entry_points  # type: ignore[import-not-found]
 
 from sphinx.domains import Domain, Index, ObjType
 from sphinx.domains.std import GenericObject, Target
diff --git a/sphinx/search/ja.py b/sphinx/search/ja.py
@@ -13,16 +13,16 @@
 import os
 import re
 import sys
-from typing import TYPE_CHECKING, Any, Dict, List
+from typing import Any
 
 try:
-    import MeCab
+    import MeCab  # type: ignore[import-not-found]
     native_module = True
 except ImportError:
     native_module = False
 
 try:
-    import janome.tokenizer
+    import janome.tokenizer  # type: ignore[import-not-found]
     janome_module = True
 except ImportError:
     janome_module = False
diff --git a/sphinx/search/zh.py b/sphinx/search/zh.py
@@ -4,14 +4,13 @@
 
 import os
 import re
-from typing import TYPE_CHECKING, Dict, List
 
 import snowballstemmer
 
 from sphinx.search import SearchLanguage
 
 try:
-    import jieba
+    import jieba  # type: ignore[import-not-found]
     JIEBA = True
 except ImportError:
     JIEBA = False
diff --git a/sphinx/testing/fixtures.py b/sphinx/testing/fixtures.py
@@ -82,7 +82,7 @@ def app_params(request: Any, test_params: dict, shared_result: SharedResult,
     if test_params['shared_result']:
         if 'srcdir' in kwargs:
             msg = 'You can not specify shared_result and srcdir in same time.'
-            raise pytest.Exception(msg)
+            pytest.fail(msg)
         kwargs['srcdir'] = test_params['shared_result']
         restore = shared_result.restore(test_params['shared_result'])
         kwargs.update(restore)
diff --git a/sphinx/themes/basic/static/searchtools.js b/sphinx/themes/basic/static/searchtools.js
@@ -99,7 +99,7 @@ const _displayItem = (item, searchTerms, highlightTerms) => {
       .then((data) => {
         if (data)
           listItem.appendChild(
-            Search.makeSearchSummary(data, searchTerms)
+            Search.makeSearchSummary(data, searchTerms, anchor)
           );
         // highlight search terms in the summary
         if (SPHINX_HIGHLIGHT_ENABLED)  // set in sphinx_highlight.js
@@ -160,11 +160,22 @@ const Search = {
   _queued_query: null,
   _pulse_status: -1,
 
-  htmlToText: (htmlString) => {
+  htmlToText: (htmlString, anchor) => {
     const htmlElement = new DOMParser().parseFromString(htmlString, 'text/html');
     htmlElement.querySelectorAll(".headerlink").forEach((el) => { el.remove() });
+    if (anchor) {
+      const anchorContent = htmlElement.querySelector(anchor);
+      if (anchorContent) return anchorContent.textContent;
+
+      console.warn(
+        `Anchor block not found. Sphinx search tries to obtain it via '${anchor}'. Check your theme or template.`
+      );
+    }
+
+    // if anchor not specified or not found, fall back to main content
     const docContent = htmlElement.querySelector('[role="main"]');
     if (docContent) return docContent.textContent;
+
     console.warn(
       "Content block not found. Sphinx search tries to obtain it via '[role=main]'. Could you check your theme or template."
     );
@@ -549,8 +560,8 @@ const Search = {
    * search summary for a given text. keywords is a list
    * of stemmed words.
    */
-  makeSearchSummary: (htmlText, keywords) => {
-    const text = Search.htmlToText(htmlText);
+  makeSearchSummary: (htmlText, keywords, anchor) => {
+    const text = Search.htmlToText(htmlText, anchor);
     if (text === "") return null;
 
     const textLower = text.toLowerCase();
diff --git a/sphinx/theming.py b/sphinx/theming.py
@@ -22,7 +22,7 @@
 if sys.version_info >= (3, 10):
     from importlib.metadata import entry_points
 else:
-    from importlib_metadata import entry_points
+    from importlib_metadata import entry_points  # type: ignore[import-not-found]
 
 if TYPE_CHECKING:
     from sphinx.application import Sphinx
diff --git a/sphinx/util/i18n.py b/sphinx/util/i18n.py
@@ -6,7 +6,7 @@
 import re
 from datetime import datetime, timezone
 from os import path
-from typing import TYPE_CHECKING, Callable, NamedTuple
+from typing import TYPE_CHECKING, NamedTuple
 
 import babel.dates
 from babel.messages.mofile import write_mo
@@ -18,10 +18,41 @@
 from sphinx.util.osutil import SEP, canon_path, relpath
 
 if TYPE_CHECKING:
+    import datetime as dt
     from collections.abc import Generator
+    from typing import Protocol, Union
+
+    from babel.core import Locale
 
     from sphinx.environment import BuildEnvironment
 
+    class DateFormatter(Protocol):
+        def __call__(  # NoQA: E704
+            self,
+            date: dt.date | None = ...,
+            format: str = ...,
+            locale: str | Locale | None = ...,
+        ) -> str: ...
+
+    class TimeFormatter(Protocol):
+        def __call__(  # NoQA: E704
+            self,
+            time: dt.time | dt.datetime | float | None = ...,
+            format: str = ...,
+            tzinfo: dt.tzinfo | None = ...,
+            locale: str | Locale | None = ...,
+        ) -> str: ...
+
+    class DatetimeFormatter(Protocol):
+        def __call__(  # NoQA: E704
+            self,
+            datetime: dt.date | dt.time | float | None = ...,
+            format: str = ...,
+            tzinfo: dt.tzinfo | None = ...,
+            locale: str | Locale | None = ...,
+        ) -> str: ...
+
+    Formatter = Union[DateFormatter, TimeFormatter, DatetimeFormatter]
 
 logger = logging.getLogger(__name__)
 
@@ -169,7 +200,7 @@ def docname_to_domain(docname: str, compaction: bool | str) -> str:
 
 
 def babel_format_date(date: datetime, format: str, locale: str,
-                      formatter: Callable = babel.dates.format_date) -> str:
+                      formatter: Formatter = babel.dates.format_date) -> str:
     # Check if we have the tzinfo attribute. If not we cannot do any time
     # related formats.
     if not hasattr(date, 'tzinfo'):
@@ -207,6 +238,7 @@ def format_date(
             # Check if we have to use a different babel formatter then
             # format_datetime, because we only want to format a date
             # or a time.
+            function: Formatter
             if token == '%x':
                 function = babel.dates.format_date
             elif token == '%X':
diff --git a/sphinx/util/rst.py b/sphinx/util/rst.py
@@ -54,7 +54,8 @@ def charwidth(char: str, widechars: str) -> int:
 def heading(env: Environment, text: str, level: int = 1) -> str:
     """Create a heading for *level*."""
     assert level <= 3
-    width = textwidth(text, WIDECHARS[env.language])
+    # ``env.language`` is injected by ``sphinx.util.template.ReSTRenderer``
+    width = textwidth(text, WIDECHARS[env.language])  # type: ignore[attr-defined]
     sectioning_char = SECTIONING_CHARS[level - 1]
     return f'{text}\n{sectioning_char * width}'
 
diff --git a/sphinx/util/tags.py b/sphinx/util/tags.py
@@ -20,8 +20,8 @@ class BooleanParser(Parser):
     Only allow condition exprs and/or/not operations.
     """
 
-    def parse_compare(self) -> Node:
-        node: Node
+    def parse_compare(self) -> nodes.Expr:
+        node: nodes.Expr
         token = self.stream.current
         if token.type == 'name':
             if token.value in ('true', 'false', 'True', 'False'):
@@ -67,7 +67,7 @@ def eval_condition(self, condition: str) -> bool:
             msg = 'chunk after expression'
             raise ValueError(msg)
 
-        def eval_node(node: Node) -> bool:
+        def eval_node(node: Node | None) -> bool:
             if isinstance(node, nodes.CondExpr):
                 if eval_node(node.test):
                     return eval_node(node.expr1)
diff --git a/sphinx/util/template.py b/sphinx/util/template.py
@@ -26,7 +26,8 @@ class BaseRenderer:
     def __init__(self, loader: BaseLoader | None = None) -> None:
         self.env = SandboxedEnvironment(loader=loader, extensions=['jinja2.ext.i18n'])
         self.env.filters['repr'] = repr
-        self.env.install_gettext_translations(get_translator())
+        # ``install_gettext_translations`` is injected by the ``jinja2.ext.i18n`` extension
+        self.env.install_gettext_translations(get_translator())  # type: ignore[attr-defined]
 
     def render(self, template_name: str, context: dict[str, Any]) -> str:
         return self.env.get_template(template_name).render(context)
diff --git a/sphinx/versioning.py b/sphinx/versioning.py
@@ -18,7 +18,7 @@
     from sphinx.application import Sphinx
 
 try:
-    import Levenshtein
+    import Levenshtein  # type: ignore[import-not-found]
     IS_SPEEDUP = True
 except ImportError:
     IS_SPEEDUP = False
diff --git a/sphinx/writers/latex.py b/sphinx/writers/latex.py
@@ -29,7 +29,7 @@
     from docutils.utils.roman import toRoman
 except ImportError:
     # In Debian/Ubuntu, roman package is provided as roman, not as docutils.utils.roman
-    from roman import toRoman  # type: ignore[no-redef]
+    from roman import toRoman  # type: ignore[no-redef, import-not-found]
 
 if TYPE_CHECKING:
     from docutils.nodes import Element, Node, Text
diff --git a/tests/js/searchtools.js b/tests/js/searchtools.js
@@ -31,6 +31,38 @@ describe('Basic html theme search', function() {
 
 });
 
+describe("htmlToText", function() {
+
+  const testHTML = `<html>
+  <div class="body" role="main">
+    <section id="getting-started">
+      <h1>Getting Started</h1>
+      <p>Some text</p>
+    </section>
+    <section id="other-section">
+      <h1>Other Section</h1>
+      <p>Other text</p>
+    </section>
+    <section id="yet-another-section">
+      <h1>Yet Another Section</h1>
+      <p>More text</p>
+    </section>
+  </div>
+  </html>`;
+
+  it("basic case", () => {
+    expect(Search.htmlToText(testHTML).trim().split(/\s+/)).toEqual([
+      'Getting', 'Started', 'Some', 'text', 
+      'Other', 'Section', 'Other', 'text', 
+      'Yet', 'Another', 'Section', 'More', 'text'
+    ]);
+  });
+
+  it("will start reading from the anchor", () => {
+    expect(Search.htmlToText(testHTML, '#other-section').trim().split(/\s+/)).toEqual(['Other', 'Section', 'Other', 'text']);
+  });
+});
+
 // This is regression test for https://github.com/sphinx-doc/sphinx/issues/3150
 describe('splitQuery regression tests', () => {
 
