move quick search box above TOC

[birkenfeld]

BPO	19489
Nosy	@birkenfeld, @ezio-melotti, @merwok, @bitdancer, @berkerpeksag, @zware, @JelleZijlstra, @ammaraskar
Files	searchbar.diff searchbar.diff2 searchbar_in_header.diff searchbar_in_header.diff2 searchbar_in_header.diff3 searchbar_in_header.diff4

^{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:

assignee = 'https://github.com/berkerpeksag'
closed_at = <Date 2016-09-09.20:12:09.865>
created_at = <Date 2013-11-04.06:28:30.626>
labels = ['easy', 'type-feature', 'docs']
title = 'move quick search box above TOC'
updated_at = <Date 2016-09-09.20:16:19.388>
user = 'https://github.com/birkenfeld'

bugs.python.org fields:

activity = <Date 2016-09-09.20:16:19.388>
actor = 'zach.ware'
assignee = 'berker.peksag'
closed = True
closed_date = <Date 2016-09-09.20:12:09.865>
closer = 'python-dev'
components = ['Documentation']
creation = <Date 2013-11-04.06:28:30.626>
creator = 'georg.brandl'
dependencies = []
files = ['43650', '43848', '43994', '43995', '44064', '44509']
hgrepos = []
issue_num = 19489
keywords = ['patch', 'easy']
message_count = 21.0
messages = ['202091', '228278', '267460', '269913', '270843', '271106', '271119', '271918', '271925', '271927', '271929', '272279', '272296', '273574', '274286', '274292', '274307', '275415', '275418', '275419', '275420']
nosy_count = 10.0
nosy_names = ['georg.brandl', 'ezio.melotti', 'eric.araujo', 'r.david.murray', 'docs@python', 'python-dev', 'berker.peksag', 'zach.ware', 'JelleZijlstra', 'ammar2']
pr_nums = []
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue19489'
versions = ['Python 3.5', 'Python 3.6']

[birkenfeld]

From Mark Summerfield:,

The Quick search box is really useful, but it is annoying that its
position varies from page to page. On pages with long tables of
contents it is often out of sight.

Why not put it above the Table of Contents. That way it is always
in the same place and easily accessible.

[BreamoreBoy]

If this is referring to the box on docs.python.org shouldn't this be logged elsewhere?

[JelleZijlstra]

Yes, I don't think we control this, the layout is generated by sphinx.

[ammaraskar]

It looks like this can be fixed by us. Since sphinx 1.0 there is this handy config parameter: http://www.sphinx-doc.org/en/stable/config.html#confval-html_sidebars

I've attached a patch which pins the searchbox as the first thing on every page.

[ammaraskar]

bump, added the documentation experts list, not sure if the core dev who made this issue is still active.

[zware]

The patch needs some work, as it stands it makes the 'Report a Bug' link disappear. I haven't looked into it far enough to determine why.

For an alternative bikeshed color, would it be possible to put the quick search in the header, just left of the 'previous | next | modules | index' links?

[ammaraskar]

Thank you for pointing that out to me, it completely slipped past.

It looks like the 'Report a Bug' link disappears because deprecated api is used in Doc/tools/templates/layout.html

{% block sidebarsourcelink %}
{% endblock %}

http://www.sphinx-doc.org/en/stable/templating.html#blocks

The following four blocks are only used for pages that do not have
assigned a list of custom sidebars in the html_sidebars config
value"

I've amended the patch to fix this by using the way they recommend with a custom html_sidebar.

As far as putting it in the title bar goes, I think it's slightly more prone to breakage since we're essentially duplicating sphinx's searchbar code. It's easy enough to add it to the right of those links, there's a {% block relbaritems %} for that. Adding it to the left is slightly more complicated. Personally I like just pinning it to the top of the sidebar but I can look into that as well if you really want.
https://github.com/sphinx-doc/sphinx/blob/master/sphinx/themes/basic/layout.html#L27-L46

[zware]

This LGTM.

If it's simple enough, I'd like to see a shot at putting the search box in the top bar, but it's not necessary :)

I'll commit this in the near future unless somebody beats me to it.

[ammaraskar]

This patch adds the search bar to the navigation/header area on the right.

[ammaraskar]

Amended the navigation bar patch to add back a change that only shows the searchbar if javascript is enabled.

[zware]

I really like the search box in the header/footer.

I can't really speak for the actual content of the patch since my Sphinx/HTML/CSS/Jinja/whatever else knowledge is severely limited, but it looks pretty straightforward and the result is very nice. I'd appreciate a review from someone who's better-versed in all things Sphinx (Georg, if you have a chance, you'd be ideal).

If there are no objections within about a week, though, I'll just go ahead and commit it.