I think this looks OK, but I was under the impression no one actually thinks the search works very well. If not, do we want it at the top?

I agree that the search is not great. But putting the search field in a varing not easily accessible place is no solution to this.

Either we want to have a search field (even with limited capability) - then it should be easily accessible at the top. Or we are a bit ashamed of the search and don't want to advertise it. Then, the search field should go completely. In that case I propose to add a "search" link next to index. That way the search is still accessible but less advertised.

Personally, I'd keep the search field. There's a lot of less useful results and the output format is not great, but at least for simple things like "xlim" it points me to the expected documentation (pyplot.xlim, Axes.get/set_xlim at the top). However, I can live with both versions, the top search field or no search field. A badly located search field just doesn't make sense.

FWIW I think the search works well and use it all the time, and it really annoys me every time I try and find the search box in the pandas docs that is hidden at the bottom of the sidebar.

@tacaswell Do you have any recommendations who should review this before merging?

I kind of like having the source readily accessible (but that may be due to my unusally good relationship with rst :-)) and doubt that anyone would really be confused by the link.
Otherwise looks fine to me.

The .rst source is not relevant for the users, so the link should not be in such a prominent place in the official docs. Additionally, the .rst contents is also quite useless in many cases, because it mostly contains headings and autodoc directives.

If there's consus that the link is of value for the developers anyway, I'd like to either show it only in the dev-docs, or alternatively make it less prominent (e.g. by moving it to the bottom of the page).

I'm not in favour of this change. I rarely if ever search websites using their internal search, and would personally prefer the navigation stay on top....

IMHO it's good UX to have permanent elements such as a search field in a fixed place. Since the navigation may become very long, the place of the search field may vary widely.

On the other hand, the search has a small fixed footprint. So the only effect is a slight constant shift of the navigation.

Note that with Sphinx 1.7 we can even reduce it further to a single line (sphinx-doc/sphinx#4377). Is it safe to assume that the docs will be built on sphinx 1.7+? If so I can update the css for the single-line search. If desired, one could also remove the title bar of the search field.

(independently of whether to keep the rst sources, I'm actually +1 in moving the search bar to the top)

I've now CSS-styled the search bar to make it single line and thus take less space at the top (This is now hardly more space than the excess whitespace the current docs have at the top of the side bar).

Note: This needs sphinx 1.7+. Since the devdocs are built with this version already, I assume this is not a limitation.

Any more opinions on whether to keep or to drop the .rst source link?

I'm +1 for getting rid of it (i.e. not that bothered, but in favour of. I'm more like +5 on moving the search box up 😛 )

rebased to fix tests.

@anntzer I understand that sometimes there is a certain value in having access to the .rst source. Would it be an option to still have a page source link, but to clearly set it apart from the regular navigation? E.g.

Having it "half hidden" as proposed is fine with me.

Page source link added back in and some layout improvements. Here's the final result