classification
Title: Online docs: make index search always available.
Type: enhancement Stage:
Components: Documentation Versions: Python 3.3, Python 3.4, Python 3.5, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Ramchandra Apte, asvetlov, docs@python, eric.araujo, ezio.melotti, georg.brandl, r.david.murray, terry.reedy
Priority: normal Keywords:

Created on 2012-09-06 17:14 by terry.reedy, last changed 2014-05-13 21:36 by skrah.

Messages (11)
msg169930 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-09-06 17:14
For the Windows Help version of the docs, the left side box has 4 tabs: Contents, Index, Search, Favorites. I now mostly use the Index tab. That means that I can enter an indexed keyword, topic, or object name and jump from place to place in the docs.

The left margin of the online docs only has a text search box equivalent to the Windows search tab (which I essentially never use). The index is only available on the front page, possibly not even visible without scrolling. Consequently, people, especially beginners, tend to use the text search box when they should be using the index. The result is often useless.

The issue came up on python-list about a beginner entering 'print' and getting nothing useful. With the Windows doc, 'print' in the index search immediately brings up print (builtin function) (twice, I did not look into why). The same thing in the search lists 153 pages, with the builtin functions page at 75. Not too surprising, as it is a long page with only 3 occurrences of 'print'. Also not useful.

So I think the online docs should also have an always available index search box in addition to the text search box (which should be properly labeled as such). 'Enter a module, class, for function name.' should be applied to index search, not text search.

An alternative is for the one box to give both index search results and text search results, but doing the latter when one only wants the former is a waste of both server and reader resources.
msg169931 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2012-09-06 17:29
The index is available on every page via the link in the upper right corner.  An index-specific search might be interesting, though I usually just click the 'index on one page' link and do a text search.  But that is a two step process and doesn't give a nice list of hits.

I don't think I ever use the text search box, either.  I just use google.
msg169933 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-06 17:31
I find the current search quite useless.
I think index search with a fallback on text search when there are no results would be better.
msg169935 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-09-06 19:22
I am not the only person who finds the 4 lines of

Quick search
[                  ] [go]
Enter search terms or a module,
class or function name. 

more eye-catching than the more useful
                                                      modules | index

in the corner. It is not even obvious what those are about. They are in black 'I am not a link' text until the mouse goes over them. So lets make them more prominent.

Second, no one finds the current, eye-catching Quick search very useful. For naive beginners, it seems to be off-putting.
The python-list thread is "python docs search for 'print'". So lets change it.

Combining these ideas, my revised suggestion is: Move the upper right entries to the sidebar above Quick search and expand and capitalize them so the sidebar would then look like

Module index
General index
Quick search
[             ]...

where the quick search is actually initially quick by first searching only the general index (Ezio's variation). (I am assuming that all modules are in the general index also). If something is found, it reports "Index entries found:" and only offers "Click here to do a full text search". If nothing is in the index, report "No index entries found, doing a full text search ..."

(This would still not be as good as the Windows doc, where the index tab starts with the entire index list and responds as each character is entered. That catches typos as mistyped. This would best be done by client-side javascript after loading the entire index list.)
msg169937 - (view) Author: Stefan Krah (skrah) * (Python committer) Date: 2012-09-06 20:09
I like the quick search: It works very well for function names.
For the use cases mentioned here I use Google.

I never use the index, so for me personally the positioning of
the quick search box is perfect.
msg169963 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-09-07 01:28
'print' *is* a function name ;-)
which also happens to be a common word.

If the current search box gives you the page where the function is defined, searching the index first should give you the same page.
msg170048 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2012-09-08 12:51
If I search for "random", at the top of the result lists I want to see at least the "random" module and the "random.random" function.

Currently the "random" module is the 4th result, and "random.random" is buried down in the list (17th place) among all the other random.* functions.

The results are generated by the query() function in searchtools.js, and AFAIU it generates 3 lists, importantResults, objectResults, unimportantResults, that get then sorted independently in alphabetic order by the object fullname, and concatenated.

I experimented a bit and one way to get exact matches to the top is to add before the switch at line 370 something like 
if (fullname == object) {
    importantResults.push(result);
    continue;
}

This will include "random", but not "random.random".
Other possible variations are 
  if ((fullname == object) || (fullname.split('.').pop() == object)) {
or
  if ((fullname == object) || $.inArray(object, fullname.split('.')) > -1)

Here fullname is e.g. "random.random", "$.inArray(object, fullname.split('.')) > -1" is the jquery equivalent of Python's "object in fullname.split('.')".

Another way to address the problem is to change the sorting algorithm to move near the top results like "random" and "random.random".
msg211506 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-02-18 10:11
This seems to have been fixed/improved already.
A search for "random" now returns the random module as first result and random.random as second.
Searching for "print" returns the pprint module first, and then the print function.
With "str" or "list" the results are a bit worse, with the builtin function in 6th and 4th position respectively.
Searching for keywords (e.g. "with") still doesn't give useful results.

The code now uses something similar to what I suggested in the previous message (if ((fullname == object) || (fullname.split('.').pop() == object)) {...}) and a scoring system.  It might still need some tweaking to get better results with "str" and "list" and for keywords, but it's already much better.

Terry, given these improvements, do you still think that using the index is better?  Are there still searches that don't return the desired results?
msg211522 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-02-18 16:43
We have collectively spent much time creating reasonably good module and term indexes and more improvements can and will be made. I strongly feel that they should be made as easily searchable and usable as the full text searches that are generally less useful to useless and are always more resource consuming.

You already answered your first question. While 'print' is listed second (but should be first)-- after a delay that would not be needed if the index were used -- it is followed by 62 lines of noise. What a waste. If the index were used, the response to 'with' would start with 'with: statement'.

As for other searches: 'if' returns hits for 'snIFf', 'dIFference', 'hexlIFy', etc, but not the 'if' statement, which would be first if the index were used; **' return no hits, whereas an index search would return the current entries for '**'. Ditto for '%' and '&'. Google and other search engines do not search for symbols. It is a shame that the search box on the docs does not either. A few years ago I collected to data needed to vastly improve the symbol index, but doing so will not do the current doc search box any good if the index is not used.
msg211528 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2014-02-18 17:38
What a waste indeed. After all, when I want to search I only ever want one single match to be displayed.
msg211553 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2014-02-18 20:48
I believe I somewhere proposed that there be an option to get more *if one wanted more*. The real waste is not using the available index resources.
History
Date User Action Args
2014-05-13 21:36:43skrahsetnosy: - skrah
2014-02-18 20:48:09terry.reedysetmessages: + msg211553
2014-02-18 17:38:56georg.brandlsetmessages: + msg211528
2014-02-18 16:43:18terry.reedysetmessages: + msg211522
2014-02-18 10:11:09ezio.melottisetmessages: + msg211506
2014-02-17 18:05:20ezio.melottisetversions: + Python 3.5, - Python 3.2
2012-09-08 22:37:55asvetlovsetnosy: + asvetlov
2012-09-08 14:59:27Ramchandra Aptesetnosy: + Ramchandra Apte
2012-09-08 12:51:30ezio.melottisetmessages: + msg170048
2012-09-07 01:28:05terry.reedysetmessages: + msg169963
2012-09-06 20:09:17skrahsetnosy: + skrah
messages: + msg169937
2012-09-06 19:22:32terry.reedysetmessages: + msg169935
2012-09-06 17:31:16ezio.melottisetmessages: + msg169933
2012-09-06 17:29:39r.david.murraysetnosy: + r.david.murray
messages: + msg169931
2012-09-06 17:14:26terry.reedycreate