[Python-ideas] Order in the documentation search results

[Hernan Grecco]

Hi,

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.

best,

Hernan

[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

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.
>>> ...
>
>