Online docs: make index search always available. #60075
Comments
|
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. |
|
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. |
|
I find the current search quite useless. |
|
I am not the only person who finds the 4 lines of Quick search more eye-catching than the more useful 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. 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 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.) |
|
I like the quick search: It works very well for function names. I never use the index, so for me personally the positioning of |
|
'print' *is* a function name ;-) If the current search box gives you the page where the function is defined, searching the index first should give you the same page. |
|
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". |
|
This seems to have been fixed/improved already. 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? |
|
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. |
|
What a waste indeed. After all, when I want to search I only ever want one single match to be displayed. |
|
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. |
|
It looks like there have at least been some improvements in this regard, especially recently—builtin functions do show up now as of the 3.11 docs (if we can backport a later sphinx version to 3.10, that might pick up the fix if its upstream, along with several others we want), index entries show up before text matches, glossary entries show up above everything else, and we can add our own glossary entries for common search queries ( It seems the main remaining immediately actionable ask here, as also discussed on python/docs-community#39 and python/docs-community#44 , is seeing if we can modify the upstream Sphinx Also, the other missing item is a way to index keywords—right now, they don't show up in search. I'm not sure what to do about that, though, since AFAIK there isn't a specific role for them and we'd want them to jump to their relevant section in the Python language reference rather than filling up the glossary with them, at least I'd think so? |
The A |
|
From the ones I looked at, they all have index directives. Assuming you make the index searchable, that should solve this too. then. |
|
See sphinx-doc/sphinx#10819 -- testing appreciated! A |
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:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: