python / python/cpython

Ordering of search results in the docs could be improved

Offen
#138,277 4 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen

Dieses Issue hat noch niemand übernommen.

docs triaged
Vorherrschende Sprache
Python
Sterne
77.2k
Forks
35.9k
PR-Merge-Kennzahlen
PR-Kennzahlen ausstehend

Beschreibung

When searching for "str" in the documentation, for example, the built-in str type shows up 44th in the list of results currently. This specific example (as well as a general notion that the search results are often not useful) was recently cited to me by a colleague as one reason that they choose to caution beginner students against using Python's docs compared to other alternatives, because the docs are "hard to navigate" and "hard to search." I disagree with that assessment on the whole, but I do think that improving the ordering of the search results would make the docs easier to use and navigate, particularly for folks just starting out with Python.

Sphinx has a mechanism for custom sorting of search results, so it should be possible to come up with some heuristics there that improve the ordering of the results. I'll put in a PR in a little while with one small step that I think is an improvement.

Linked PRs
  • gh-138278

Beitragsleitfaden

Beitragsleitfaden öffnen

Erste Schritte

  1. Lies das ganze Issue und danach den Beitragsleitfaden des Projekts.
  2. Schreib ins Issue, dass du es übernimmst — das erspart doppelte Arbeit.
  3. Forke das Repository und arbeite in einem Branch.
  4. Öffne einen Pull Request, der die Issue-Nummer nennt.

Rechercherichtung

Überprüfe den verlinkten PR gh-138278 und den im Issue erwähnten benutzerdefinierten Sortiermechanismus für Suchergebnisse von Sphinx. Verwende das Suchbeispiel "str" als erste Prüfung und betrachte die Arbeit als abgeschlossen, wenn die resultierende Reihenfolge für Benutzer der Dokumentation nachweislich nützlicher ist.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
python
Bereich
documentation, search
Issue-Typ
Feature
Schwierigkeit
5/5
Geschätzter Aufwand
Über eine Woche
Aktivitätsstatus
Veraltet
Klarheit
Größtenteils klar
Anfängerfreundlichkeit
20/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.