Repository navigation
Docs search should prominently show definitions and glossary items #78579
Description
| BPO | 34398 |
|---|---|
| Nosy | @berkerpeksag, @willingc, @JulienPalard, @ammaraskar, @Mariatta, @csabella, @jfine2358 |
| PRs |
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 = None
closed_at = <Date 2021-04-02.15:52:32.256>
created_at = <Date 2018-08-14.07:52:28.363>
labels = ['3.8', 'type-bug', '3.7', 'docs']
title = 'Docs search should prominently show definitions and glossary items'
updated_at = <Date 2021-04-02.15:52:32.256>
user = 'https://github.com/jfine2358'bugs.python.org fields:
activity = <Date 2021-04-02.15:52:32.256>
actor = 'ammar2'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-04-02.15:52:32.256>
closer = 'ammar2'
components = ['Documentation']
creation = <Date 2018-08-14.07:52:28.363>
creator = 'jfine2358'
dependencies = []
files = []
hgrepos = []
issue_num = 34398
keywords = ['patch']
message_count = 12.0
messages = ['323503', '323528', '323529', '323554', '323557', '323567', '323568', '323569', '334941', '352865', '383319', '390074']
nosy_count = 8.0
nosy_names = ['docs@python', 'berker.peksag', 'willingc', 'mdk', 'ammar2', 'Mariatta', 'cheryl.sabella', 'jfine2358']
pr_nums = ['8773']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue34398'
versions = ['Python 3.7', 'Python 3.8']
Activity
jfine2358 commentedon Aug 14, 2018
The docs contain a very useful page https://docs.python.org/3.5/glossary.html. However, the search feature does not index the glossary.
Thus, the search https://docs.python.org/3.5/search.html?q=iterable does not produce the helpful glossary entry
===
iterable
An object capable of returning its members one at a time. Examples of iterables include all sequence types (such as list, str, and tuple) and some non-sequence types like dict, file objects, and objects of any [...]
===
bpo-788509 is the only docs issue I could find, whose title contains glossary. It gives insight into the thoughts then about the tutorial. In msg44460 Skip Montaro says (1) that the glossary is "for the tutorial", and (2) he'd like to improve links into the tutorial.
I suggest that part of the fix for this issue is on the home page page Glossary in the first grouping "Parts of the documentation."
Mariatta commentedon Aug 14, 2018
Hmm the search is built-in functionality in Sphinx, and I don't think we have any way to control or customize that.
jfine2358 commentedon Aug 14, 2018
Good discovery. The glossary uses the RST glossary directive.
https://github.com/python/cpython/blob/master/Doc/glossary.rst
The Sphinx docs have a glossary, which is indexed by its search.
http://www.sphinx-doc.org/en/master/search.html?q=domain
So maybe Sphinx already has the functionality we require. Perhaps it's simply a matter of configuring the Python docs to use it. (This is optimism.)
ammaraskar commentedon Aug 15, 2018
Hmm, are you sure its not indexed? Look at this search result: https://docs.python.org/3/search.html?q=__slots__
The glossary page shows up in the results for me.
Or are you suggesting that if you search for a term defined in the glossary, it be prominently shown at the top of the search page?
jfine2358 commentedon Aug 15, 2018
You're right! Thank you. However, there's still a problem. A user searches for a technical term, and the carefully written glossary entry defining it does not appear.
For my search term (iterable), there was a single entry with a link to the Glossary page, whose associated text was simply the first few entries in the glossary.
===
Glossary
...active shell when entering code for an indented code block or within a pair of matching left and right delimiters (parentheses, square brackets or curly braces). 2to3 A tool that tries to convert Python 2.x code to Pyt...
===
On a related matter. Sphinx provides an anchor, used for internal navigation with the glossary. But it doesn't provide a permalink to that anchor. Compare
https://docs.python.org/3.5/glossary.html#term-iterable
https://docs.python.org/3.5/reference/compound_stmts.html#with
I think there's a real problem, and that my initial diagnosis was wrong. So I've changed the issue title slightly. (I hope you don't mind.)
The problem is, perhaps, that it is the glossary page that is indexed, rather than the glossary items. Another fix would be, as you suggest, pop up at top of results page a glossary item.
[-]Docs search does not index glossary[/-][+]Docs search does not index glossary items[/+]ammaraskar commentedon Aug 15, 2018
I think showing glossary results up top in the search page is a good idea, so I wrote up a quick proof of concept sphinx extension to do so. The diff isn't very big or complicated but it does need a bit of cleanup, especially the javascript and presentation side.
There are some screenshots in the pull request.
(Adding Berker since they reviewed the change to move the search bar in the header for the docs)
jfine2358 commentedon Aug 15, 2018
Thank you for this, Ammar. Proof of concept solution is good progress. I'm well impressed. The screen shots convince me that it's well worth doing.
For me, the one thing that's missing is a link just above the glossary item. Something like "Glossary: iterable". You're probably aware of this, and so far it's only proof-of-concept.
Oh, and of course that the links in the displayed item work. My be a gotcha here for links to other glossary items.
So, well done, and thank you very much.
berkerpeksag commentedon Aug 15, 2018
Ammar's pull request looks good to me, but it would be nice to include the item's title in the box. I will add my comments about the design and implementation in the pull request.
csabella commentedon Feb 6, 2019
@ammar2, this looks like a great addition to the docs. Would you be able to address Berker's request and also fix the merge conflict on the PR?
Also adding Julien and Carol from the expert's index for documentation.
ammaraskar commentedon Sep 20, 2019
Changing the title a little to represent that this is now a general improvement of the docs search. Julien is working to upstream a solution into Sphinx that will allow any items to be featured prominently on search.
[-]Docs search does not index glossary items[/-][+]Docs search should prominently show definitions and glossary items[/+]JulienPalard commentedon Dec 18, 2020
New changeset 8c5d034 by Ammar Askar in branch 'master':
bpo-34398: Allow glossary results to show up on search page (GH-8773)
8c5d034
ammaraskar commentedon Apr 2, 2021
Thank you to Julien for reviewing, we ended up going with our own solution instead of waiting on Sphinx and I think it looks good :)