This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: Docs search should prominently show definitions and glossary items
Type: behavior Stage: resolved
Components: Documentation Versions: Python 3.8, Python 3.7
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Mariatta, ammar2, berker.peksag, cheryl.sabella, docs@python, jfine2358, mdk, willingc
Priority: normal Keywords: patch

Created on 2018-08-14 07:52 by jfine2358, last changed 2022-04-11 14:59 by admin. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 8773 merged ammar2, 2018-08-15 13:48
Messages (12)
msg323503 - (view) Author: Jonathan Fine (jfine2358) * Date: 2018-08-14 07:52
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  [...]
===

#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."
msg323528 - (view) Author: Mariatta (Mariatta) * (Python committer) Date: 2018-08-14 15:25
Hmm the search is built-in functionality in Sphinx, and I don't think we have any way to control or customize that.
msg323529 - (view) Author: Jonathan Fine (jfine2358) * Date: 2018-08-14 15:58
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.)
msg323554 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2018-08-15 07:16
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?
msg323557 - (view) Author: Jonathan Fine (jfine2358) * Date: 2018-08-15 08:08
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.
msg323567 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2018-08-15 13:50
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)
msg323568 - (view) Author: Jonathan Fine (jfine2358) * Date: 2018-08-15 14:00
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.
msg323569 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-08-15 14:05
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.
msg334941 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-02-06 14:42
@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.
msg352865 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2019-09-20 16:18
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.
msg383319 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2020-12-18 19:00
New changeset 8c5d0347efd16f16dfb9596715e449cd928b89c8 by Ammar Askar in branch 'master':
bpo-34398: Allow glossary results to show up on search page (GH-8773)
https://github.com/python/cpython/commit/8c5d0347efd16f16dfb9596715e449cd928b89c8
msg390074 - (view) Author: Ammar Askar (ammar2) * (Python committer) Date: 2021-04-02 15:52
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 :)
History
Date User Action Args
2022-04-11 14:59:04adminsetgithub: 78579
2021-04-02 15:52:32ammar2setstatus: open -> closed
resolution: fixed
messages: + msg390074

stage: patch review -> resolved
2020-12-18 19:00:59mdksetmessages: + msg383319
2019-09-21 01:37:37ammar2linkissue38231 superseder
2019-09-20 16:18:09ammar2setmessages: + msg352865
title: Docs search does not index glossary items -> Docs search should prominently show definitions and glossary items
2019-02-06 14:42:43cheryl.sabellasetnosy: + willingc, cheryl.sabella, mdk

messages: + msg334941
versions: - Python 3.6
2018-08-15 14:05:52berker.peksagsetresolution: third party -> (no value)
messages: + msg323569
2018-08-15 14:00:27jfine2358setmessages: + msg323568
2018-08-15 13:50:40ammar2setnosy: + berker.peksag
messages: + msg323567
2018-08-15 13:48:16ammar2setkeywords: + patch
stage: patch review
pull_requests: + pull_request8248
2018-08-15 08:08:48jfine2358setmessages: + msg323557
title: Docs search does not index glossary -> Docs search does not index glossary items
2018-08-15 07:16:31ammar2setnosy: + ammar2
messages: + msg323554
2018-08-14 15:58:55jfine2358setstatus: pending -> open

messages: + msg323529
2018-08-14 15:25:42Mariattasetstatus: open -> pending
versions: - Python 2.7, Python 3.4, Python 3.5
nosy: + Mariatta

messages: + msg323528

resolution: third party
2018-08-14 07:52:28jfine2358create