Added scroll to text fragment to search.

Author: sarahboyce

docs/models.py

@@ -28,6 +28,8 @@
 from .search import (
     DEFAULT_TEXT_SEARCH_CONFIG,
     DOCUMENT_SEARCH_VECTOR,
+    START_SEL,
+    STOP_SEL,
     TSEARCH_CONFIG_LANGUAGES,
 )
 
@@ -265,15 +267,15 @@ def search(self, query_text, release):
                     headline=SearchHeadline(
                         "title",
                         search_query,
-                        start_sel="<mark>",
-                        stop_sel="</mark>",
+                        start_sel=START_SEL,
+                        stop_sel=STOP_SEL,
                         config=models.F("config"),
                     ),
                     highlight=SearchHeadline(
                         KeyTextTransform("body", "metadata"),
                         search_query,
-                        start_sel="<mark>",
-                        stop_sel="</mark>",
+                        start_sel=START_SEL,
+                        stop_sel=STOP_SEL,
                         config=models.F("config"),
                     ),
                     breadcrumbs=models.F("metadata__breadcrumbs"),

docs/search.py

@@ -48,3 +48,6 @@
         KeyTextTransform("parents", "metadata"), weight="D", config=F("config")
     )
 )
+
+START_SEL = "<mark>"
+STOP_SEL = "</mark>"

docs/templates/docs/search_results.html

@@ -36,7 +36,7 @@ <h2>{% trans "No search query given" %}</h2>
         {% for result in page.object_list %}
           <dt>
             <h2 class="result-title">
-              <a href="{% url 'document-detail' lang=result.release.lang version=result.release.version url=result.path host 'docs' %}">{{ result.headline|safe }}</a>
+              <a href="{% url 'document-detail' lang=result.release.lang version=result.release.version url=result.path host 'docs' %}{% if not start_sel in result.headline %}{{ result.highlight|fragment }}{% endif %}">{{ result.headline|safe }}</a>
             </h2>
             <span class="meta breadcrumbs">
               {% for breadcrumb in result.breadcrumbs %}

docs/templatetags/docs.py

@@ -1,4 +1,8 @@
+import re
+from urllib.parse import quote
+
 from django import template
+from django.template.defaultfilters import stringfilter
 from django.utils.safestring import mark_safe
 from django.utils.version import get_version_tuple
 from pygments import highlight
@@ -7,6 +11,7 @@
 
 from ..forms import DocSearchForm
 from ..models import DocumentRelease
+from ..search import START_SEL, STOP_SEL
 from ..utils import get_doc_path, get_doc_root
 
 register = template.Library()
@@ -81,3 +86,38 @@ def view_article(request, pk):
     nodelist = parser.parse(("endpygment",))
     parser.delete_first_token()
     return PygmentsNode(parser.compile_filter(tokens[1]), nodelist)
+
+
+@register.filter(name="fragment")
+@stringfilter
+def generate_scroll_to_text_fragment(highlighted_text):
+    """
+    Given the highlighted text generated from Document.objects.search()
+    constructs a scroll to text fragment.
+
+    This will not work when:
+    *  the highlighted test starts from a partial word, e.g it starts from
+       test_environment rather than DiscoverRunner.setup_test_environment().
+    *  it is trying to highlight a Python code snippet and the spacing logic
+       has fallen down e.g. test = 5 not test=5 but test(a=5) not test(a = 5).
+    """
+    first_non_empty_line = next(
+        (
+            stripped
+            for line in highlighted_text.split("\n")
+            if (stripped := line.strip())
+        ),
+        "",
+    )
+    # Remove highlight tags and unwanted symbols.
+    line_without_highlight = re.sub(
+        rf"{START_SEL}|{STOP_SEL}|¶", "", first_non_empty_line
+    )
+    line_without_highlight = line_without_highlight.replace(""", '"')
+    # Remove excess spacing.
+    single_spaced = re.sub(r"\s+", " ", line_without_highlight).strip()
+    # Handle punctuation spacing.
+    single_spaced = re.sub(r"\s([.,;:!?)(\]\[])", r"\1", single_spaced)
+    # Due to Python code such as timezone.now(), remove the space after a bracket.
+    single_spaced = re.sub(r"([(\[])\s", r"\1", single_spaced)
+    return f"#:~:text={quote(single_spaced)}"

docs/tests.py

@@ -19,7 +19,7 @@
 
 from .models import DOCUMENT_SEARCH_VECTOR, Document, DocumentRelease
 from .sitemaps import DocsSitemap
-from .templatetags.docs import get_all_doc_versions
+from .templatetags.docs import generate_scroll_to_text_fragment, get_all_doc_versions
 from .utils import get_doc_path, sanitize_for_trigram
 
 
@@ -252,6 +252,80 @@ def band_listing(request):
             """,
         )
 
+    def test_fragment_template_tag(self):
+        highlighted_text = """<mark>testing</mark> frameworks   section of   Advanced <mark>testing</mark> topics  .
+        Writing and running <mark>tests</mark>
+        <mark>Testing</mark> tools
+        Advanced <mark>testing</mark>
+        <mark>tests</mark> ¶"""
+        template = Template(
+            "{% load docs %}"
+            "https://docs.djangoproject.com/en/5.1/topics/testing/"
+            "{{ highlighted_text|fragment }}"
+        )
+        self.assertHTMLEqual(
+            template.render(Context({"highlighted_text": highlighted_text})),
+            "https://docs.djangoproject.com/en/5.1/topics/testing/"
+            "#:~:text=testing%20frameworks%20section%20of%20Advanced%20testing%20topics.",
+        )
+
+    def test_generate_scroll_to_text_fragment(self):
+        cases = [
+            (
+                """"<mark>StackedInline</mark>     [source]    ¶
+                The admin interface has the ability to edit models""",
+                "#:~:text=%22StackedInline%5Bsource%5D",
+            ),
+            (
+                """<mark>TextChoices</mark>  ):
+                         FRESHMAN   =   &quot;FR&quot;  ,   _  (  &quot;Freshman&quot;  )
+                         SOPHOMORE   =   &quot;SO&quot;  ,   _  (  &quot;Sophomore&quot;  )
+                         JUNIOR""",
+                "#:~:text=TextChoices%29%3A",
+            ),
+            (
+                """<mark>TextChoices</mark>  (  &quot;Medal&quot;  ,   &quot;GOLD SILVER BRONZE&quot;  )
+
+                    SPORT_CHOICES   =   [
+                        (  &quot;Martial Arts&quot;  ,   [(  &quot;judo""",
+                "#:~:text=TextChoices%28%22Medal%22%2C%20%22GOLD%20SILVER%20BRONZE%22%29",
+            ),
+            (
+                """<mark>TextChoices</mark>  ,   IntegerChoices  , and   Choices
+                are now available as a way to define    Field.choices   .   <mark>TextChoices</mark>
+                and   IntegerChoices""",
+                "#:~:text=TextChoices%2C%20IntegerChoices%2C%20and%20Choices",
+            ),
+            (
+                """<mark>TextChoices</mark>   or   IntegerChoices  ) instances.
+                Any Django field
+                Any function or method reference (e.g.   datetime.datetime.today  ) (must""",
+                "#:~:text=TextChoices%20or%20IntegerChoices%29%20instances.",
+            ),
+            (
+                """<mark>database</mark> configuration in    <mark>DATABASES</mark>   :
+
+                settings.py    ¶
+                <mark>DATABASES</mark>   =   {
+                &quot;default&quot;  :   {
+                    &quot;ENGINE&quot;  :   &quot;django.db.backends.postgresql&quot;  ,
+                    &quot;OPTIONS""",
+                "#:~:text=database%20configuration%20in%20DATABASES%3A",
+            ),
+            (
+                """
+                <mark>Generic</mark> <mark>views</mark> ¶
+                See   Built-in class-based <mark>views</mark> API  . """,
+                "#:~:text=Generic%20views",
+            ),
+        ]
+        for text, url_text_fragment in cases:
+            with self.subTest(url_text_fragment=url_text_fragment):
+                self.assertEqual(
+                    generate_scroll_to_text_fragment(text),
+                    url_text_fragment,
+                )
+
 
 class TestUtils(TestCase):
     def test_get_doc_path(self):

docs/views.py

@@ -16,6 +16,7 @@
 
 from .forms import DocSearchForm
 from .models import Document, DocumentRelease
+from .search import START_SEL
 from .utils import get_doc_path_or_404, get_doc_root_or_404
 
 SIMPLE_SEARCH_OPERATORS = ["+", "|", "-", '"', "*", "(", ")", "~"]
@@ -215,6 +216,7 @@ def search_results(request, lang, version, per_page=10, orphans=3):
                     "query": q,
                     "page": page,
                     "paginator": paginator,
+                    "start_sel": START_SEL,
                 }
             )