Added documentation type filtering to search.

Thank you to Paulo Melchiorre, Tom Carrick and Marijke Luttekes for the reviews.

Author: sarahboyce

djangoproject/scss/_style.scss

@@ -2563,6 +2563,40 @@ table.docutils th {
     }
 }
 
+search.filters {
+    @include sans-serif;
+
+    display: flex;
+    gap: 10px;
+    border-bottom: 2px solid var(--hairline-color);
+    overflow-x: auto;
+    white-space: nowrap;
+    padding-bottom: 0;
+    position: relative;
+
+    a {
+      padding: 10px 20px;
+      text-decoration: none;
+      border-bottom: 3px solid transparent;
+      transition: color 0.3s ease, border-bottom 0.3s ease;
+      color: var(--text-light);
+      flex-shrink: 0;
+
+      &:not([href]) {
+        color: var(--body-fg);
+        font-weight: bold;
+        border-bottom: 3px solid var(--primary);
+      }
+
+      &[href]:focus,
+      &[href]:active,
+      &[href]:hover {
+        outline: none;
+        border-bottom: 3px solid var(--hairline-color);
+      }
+    }
+}
+
 .search-links {
     @extend .list-links;
 

docs/models.py

@@ -244,14 +244,19 @@ def breadcrumbs(self, document):
         else:
             return self.none()
 
-    def search(self, query_text, release):
+    def search(self, query_text, release, document_type=None):
         """Use full-text search to return documents matching query_text."""
         query_text = query_text.strip()
         if query_text:
             search_query = SearchQuery(
                 query_text, config=models.F("config"), search_type="websearch"
             )
             search_rank = SearchRank(models.F("search"), search_query)
+            base_filter = Q(release_id=release.id)
+            if document_type:
+                base_filter = base_filter & Q(
+                    metadata__parents__startswith=document_type
+                )
             base_qs = (
                 self.prefetch_related(
                     Prefetch(
@@ -262,7 +267,7 @@ def search(self, query_text, release):
                         "release__release", queryset=Release.objects.only("version")
                     ),
                 )
-                .filter(release_id=release.id)
+                .filter(base_filter)
                 .annotate(
                     headline=SearchHeadline(
                         "title",

docs/search.py

@@ -1,6 +1,7 @@
 from django.contrib.postgres.search import SearchVector
 from django.db.models import F
 from django.db.models.fields.json import KeyTextTransform
+from django.utils.translation import gettext_lazy as _
 
 # Imported from
 # https://github.com/postgres/postgres/blob/REL_14_STABLE/src/bin/initdb/initdb.c#L659
@@ -51,3 +52,10 @@
 
 START_SEL = "<mark>"
 STOP_SEL = "</mark>"
+
+DOCUMENT_TYPES = {
+    "ref": _("API Reference"),
+    "topics": _("Using Django"),
+    "howto": _("How-to guides"),
+    "releases": _("Release notes"),
+}

docs/templates/docs/search_results.html

@@ -11,6 +11,13 @@
 
 {% block body %}
   {% if query %}
+    <search class="filters">
+      <span id="search-filters" class="visually-hidden">{% translate "Filter the current search results by documentation type" %}</span>
+      <a{% if not active_type %} aria-current="page"{% else %} href="{% querystring type=None page=None %}"{% endif %}>{% translate "All" %}</a>
+      {% for type, type_title in document_types.items %}
+        <a{% if active_type == type %} aria-current="page"{% else %} href="{% querystring type=type page=None %}"{% endif %}>{{ type_title }}</a>
+      {% endfor %}
+    </search>
     <h2>
       {% if release.is_dev %}
         {% blocktranslate count num_results=paginator.count trimmed %}
@@ -49,6 +56,15 @@ <h2 class="result-title">
               …&nbsp;{{ result.highlight|cut:"¶"|safe }}&nbsp;…
             {% endif %}
           </dd>
+        {% empty %}
+          {% if active_type %}
+            <dt>
+              <p>
+                {% querystring type=None page=None as all_search %}
+                {% blocktranslate trimmed %}Please try searching <a href="{{ all_search }}">all documentation results</a>.{% endblocktranslate %}
+              </p>
+            </dt>
+          {% endif %}
         {% endfor %}
       </dl>
     </div>

docs/tests/test_views.py

@@ -9,6 +9,7 @@
 from releases.models import Release
 
 from ..models import Document, DocumentRelease
+from ..search import DOCUMENT_TYPES
 from ..sitemaps import DocsSitemap
 
 
@@ -47,6 +48,29 @@ def setUpTestData(cls):
         Site.objects.create(name="Django test", domain="example2.com")
         cls.release = Release.objects.create(version="5.1")
         cls.doc_release = DocumentRelease.objects.create(release=cls.release)
+        cls.active_filter = '<a aria-current="page">'
+
+        for doc_type, title in DOCUMENT_TYPES.items():
+            Document.objects.create(
+                **{
+                    "metadata": {
+                        "body": "Generic Views",
+                        "breadcrumbs": [
+                            {"path": doc_type, "title": str(title)},
+                        ],
+                        "parents": doc_type,
+                        "slug": "generic-views",
+                        "title": "Generic views",
+                        "toc": (
+                            '<ul>\n<li><a class="reference internal" href="#">'
+                            "Generic views</a></li>\n</ul>\n"
+                        ),
+                    },
+                    "path": f"{doc_type}/generic-views",
+                    "release": cls.doc_release,
+                    "title": "Generic views",
+                }
+            )
 
     @classmethod
     def tearDownClass(cls):
@@ -60,6 +84,68 @@ def test_empty_get(self):
         )
         self.assertEqual(response.status_code, 200)
 
+    def test_search_type_filter_all(self):
+        response = self.client.get(
+            "/en/5.1/search/?q=generic",
+            headers={"host": "docs.djangoproject.localhost:8000"},
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(
+            response, "4 results for <em>generic</em> in version 5.1", html=True
+        )
+        self.assertContains(response, self.active_filter, count=1)
+        self.assertContains(response, f"{self.active_filter}All</a>", html=True)
+
+    def test_search_type_filter_by_doc_types(self):
+        for doc_type, title in DOCUMENT_TYPES.items():
+            with self.subTest(type=doc_type):
+                response = self.client.get(
+                    f"/en/5.1/search/?q=generic&type={doc_type}",
+                    headers={"host": "docs.djangoproject.localhost:8000"},
+                )
+                self.assertEqual(response.status_code, 200)
+                self.assertContains(
+                    response,
+                    "Only 1 result for <em>generic</em> in version 5.1",
+                    html=True,
+                )
+                self.assertContains(response, self.active_filter, count=1)
+                self.assertContains(
+                    response, f"{self.active_filter}{title}</a>", html=True
+                )
+                self.assertContains(response, '<a href="?q=generic">All</a>', html=True)
+
+    def test_search_type_filter_invalid_doc_types(self):
+        response = self.client.get(
+            "/en/5.1/search/?q=generic&type=invalid-so-ignored",
+            headers={"host": "docs.djangoproject.localhost:8000"},
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(
+            response, "4 results for <em>generic</em> in version 5.1", html=True
+        )
+        self.assertContains(response, self.active_filter, count=1)
+        self.assertContains(response, f"{self.active_filter}All</a>", html=True)
+
+    def test_search_type_filter_no_results(self):
+        response = self.client.get(
+            "/en/5.1/search/?q=potato&type=ref",
+            headers={"host": "docs.djangoproject.localhost:8000"},
+        )
+        self.assertEqual(response.status_code, 200)
+        self.assertContains(response, self.active_filter, count=1)
+        self.assertContains(
+            response, f"{self.active_filter}API Reference</a>", html=True
+        )
+        self.assertContains(
+            response, "0 results for <em>potato</em> in version 5.1", html=True
+        )
+        self.assertContains(
+            response,
+            'Please try searching <a href="?q=potato">all documentation results</a>.',
+            html=True,
+        )
+
 
 class SitemapTests(TestCase):
     fixtures = ["doc_test_fixtures"]

docs/views.py

@@ -16,7 +16,7 @@
 
 from .forms import DocSearchForm
 from .models import Document, DocumentRelease
-from .search import START_SEL
+from .search import DOCUMENT_TYPES, START_SEL
 from .utils import get_doc_path_or_404, get_doc_root_or_404
 
 SIMPLE_SEARCH_OPERATORS = ["+", "|", "-", '"', "*", "(", ")", "~"]
@@ -188,7 +188,9 @@ def search_results(request, lang, version, per_page=10, orphans=3):
             if exact is not None:
                 return redirect(exact)
 
-            results = Document.objects.search(q, release)
+            type_key = request.GET.get("type")
+            type_key = type_key if type_key in DOCUMENT_TYPES.keys() else None
+            results = Document.objects.search(q, release, document_type=type_key)
 
             page_number = request.GET.get("page") or 1
             paginator = Paginator(results, per_page=per_page, orphans=orphans)
@@ -217,6 +219,9 @@ def search_results(request, lang, version, per_page=10, orphans=3):
                     "page": page,
                     "paginator": paginator,
                     "start_sel": START_SEL,
+                    "active_type": type_key,
+                    "active_type_title": DOCUMENT_TYPES.get(type_key),
+                    "document_types": DOCUMENT_TYPES,
                 }
             )