Search doesn't find built-in functions

[kimoldfield]

BPO	37862
Nosy	@terryjreedy, @ammaraskar

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-08-15.01:13:06.664>
labels = ['3.8', 'type-bug', '3.7', '3.9', 'docs']
title = "Search doesn't find built-in functions"
updated_at = <Date 2019-08-22.05:28:36.105>
user = 'https://bugs.python.org/kimoldfield'

bugs.python.org fields:

activity = <Date 2019-08-22.05:28:36.105>
actor = 'terry.reedy'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2019-08-15.01:13:06.664>
creator = 'kim.oldfield'
dependencies = []
files = []
hgrepos = []
issue_num = 37862
keywords = []
message_count = 5.0
messages = ['349781', '349937', '350152', '350153', '350157']
nosy_count = 4.0
nosy_names = ['terry.reedy', 'docs@python', 'ammar2', 'kim.oldfield']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue37862'
versions = ['Python 2.7', 'Python 3.7', 'Python 3.8', 'Python 3.9']

[kimoldfield]

The python 3 documentation search
https://docs.python.org/3/search.html
doesn't always find built-in functions.

For example, searching for "zip" takes me to
https://docs.python.org/3/search.html?q=zip

I would expect the first match to be a link to
https://docs.python.org/3/library/functions.html#zip
but I can't see a link to this page anywhere in the 146 results.

[terryjreedy]

The search page is the last thing one should use. There is the index
https://docs.python.org/3/genindex-Z.html
and for builtin function, chapter 2 of the library manual.
https://docs.python.org/3/library/functions.html#built-in-functions

I don't know if the operation of the search page is documented anytwhere.

[kimoldfield]

Usually the search page is the quickest way to find documentation about a module or function - quicker than navigating through a couple of levels of pages (documentation home, index, index by letter, scroll or search in page to find desired name, click on name).

Searching for builtin functions is inconsistent. Some functions (eg getattr) are found as expected in a search, while other functions (eg zip and many others) aren't found in the search results. This could easily lead someone to incorrectly concluding that the function they are search for doesn't exist in python.

I find the response of "The search page is the last thing one should use" strange. Surely as the option to search is there, and it mostly works, we should be making incremental improvements as necessary to make it better so that everyone can easily find the right parts of the python documentation.

[ammaraskar]

See also https://bugs.python.org/issue34398

There is some related work done by Julien there as well: https://github.com/JulienPalard/pydocsearch

[terryjreedy]

Even if click 'Library Reference', click '2. Built-in...', click name in the index at the top of the page to go to the entry I know I want to read is sometimes slower that 'click search box', enter word, hit Return, wait for results, scan results to find that entry, I prefer a consistent and dependable result.

That said, perhaps the search algorithm should start with looking words up in the builtins list, the module index, the glossary, and the index, and display those first Index pages with definitions should get heavy weight too. But is seems from your example that the obvious places might be downweighted instead.

As for my answer, I believe that the search once used Google, which was and still is terrible at returning results from the current doc. For instance, just now, the 2nd return for 'Python zip' is the zip entry in chapter 2 ... for 3.3.7! 'Python zip 3.7' does return
https://docs.python.org/3/library/functions.html
as first entry. I would rather click click to get to the same place.

If Julien and Ammar can improve Search [ ] to beat that, and be consistently useful to beginners, more power to them.

[iritkatriel]

For example, searching for "zip" takes me to https://docs.python.org/3/search.html?q=zip

I would expect the first match to be a link to https://docs.python.org/3/library/functions.html#zip but I can't see a link to this page anywhere in the 146 results.

This must have changed by now, because I do get the builtin zip as one of the top results (not the first though):