[Python-ideas] Order in the documentation search results

[Stefan Drees]

Hi Hernan,

On 03.01.13 05:05, Hernan Grecco wrote:
> ... I have done some work to improve the search results on the Python
> Docs. You can compare the current [0] with the proposed [1], or both
> at the same time [2]. It is basically a patch for sphinx [4], plus a
> python specific javascript [3]. The ideas are briefly explained [4].
>
> I have not optimized the scores in [4], just some educated guesses.
> ...
>
> [0] http://hgrecco.github.com/searchpydocs/current/
> [1] http://hgrecco.github.com/searchpydocs/proposed/
> [2] http://hgrecco.github.com/searchpydocs/
> [3] https://github.com/hgrecco/searchpydocs/blob/master/cpy_scorer.js
> [4] https://bitbucket.org/birkenfeld/sphinx/issue/1067/better-search-results
>

that looks good to me for eg. file, dict and dict.clear. Far better, 
than a google/bing/whatever_external  search by the way (as tested with 
dict, using google search on "dict site:http://docs.python.org/3/") :-))

As I read in the sphinx issue mail flow you opened, Georg asks for a 
pull request of the patches. I consider this very promising. Thanks 
again for the effort and these good first results Hernan!

All the best,
Stefan.

Further historic details:

> On Wed, Jan 2, 2013 at 1:37 PM, Stefan Drees <stefan at drees.name> wrote:
>> Hi hernan,
>> On 02.01.13 12:20, Hernan Grecco wrote:
>>>
>>> ... Thanks for all the feedback. I was hacking the sphinx indexer and the
>>>
>>> javacript searchtool today. I think the search results can be improved
>>> by patching sphinx upstream and adding a small project dependent (in
>>> this case Python) javascript snippet. I have created a proposal in the
>>> Sphinx Issue tracker [0]. Let's move the discussion there.
>>> ...
>>> [0]
>>> https://bitbucket.org/birkenfeld/sphinx/issue/1067/better-search-results
>>
>>
>> thanks a lot for transforming the mail thread to improve the local search
>> facility into real code suggestions.
>>
>> I commented on a first snippet from your suggested patch there.
>>
>> All the best,
>> Stefan.
>>
>> Further historic details:
>>>
>>>
>>> On Mon, Dec 31, 2012 at 8:47 AM, Stefan Drees <stefan at drees.name> wrote:
>>>>
>>>> On 30.12.12 20:45, Georg Brandl wrote:
>>>>>
>>>>> On 12/30/2012 07:11 PM, Ned Batchelder wrote:
>>>>>>
>>>>>> On 12/30/2012 12:54 PM, Hernan Grecco wrote:
>>>>>>>
>>>>>>> ...
>>>>>>>
>>>>>>> I have seen many people new to Python stumbling while using the Python
>>>>>>> docs due to the order of the search results.
>>>>>>> ...
>>>>>>>
>>>>>>> So my suggestion is to put the builtins first, the rest of the
>>>>>>> standard lib later including HowTos, FAQ, etc and finally the
>>>>>>> c-modules. Additionally, a section with a title matching exactly the
>>>>>>> search query should come first. (I am not sure if the last suggestion
>>>>>>> belongs in python-ideas or in
>>>>>>> the sphinx mailing list, please advice)
>>>>>>
>>>>>>
>>>>>>
>>>>>> While we're on the topic, why in this day and age do we have a custom
>>>>>> search?  Using google site search would be faster for the user, and
>>>>>> more
>>>>>> accurate.
>>>>>
>>>>>
>>>>>
>>>>> I agree.  Someone needs to propose a patch though.
>>>>> ...
>>>>
>>>>
>>>>
>>>> a custom search in itself is a wonderful thing. To me it also shows more
>>>> appreciation of visitor concerns than thoses sites, that are just
>>>> _offering_
>>>> google site search (which is accessible anyway to every visitor capable
>>>> of
>>>> memorizing the google or bing or whatnot URL).
>>>>
>>>> I second Hernans suggestion about ordering and also his question where
>>>> the
>>>> request (and patches) should be directed to.
>>>> ...