[Python-ideas] Order in the documentation search results (original) (raw)

Stefan Drees stefan at drees.name
Thu Jan 3 10:05:27 CET 2013

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

More information about the Python-ideas mailing list