[issue34398] Docs search does not index glossary
New submission from Jonathan Fine jfine2358@gmail.com:
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."
---------- assignee: docs@python components: Documentation messages: 323503 nosy: docs@python, jfine2358 priority: normal severity: normal status: open title: Docs search does not index glossary type: behavior versions: Python 2.7, Python 3.4, Python 3.5, Python 3.6, Python 3.7, Python 3.8
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Mariatta Wijaya mariatta.wijaya@gmail.com added the comment:
Hmm the search is built-in functionality in Sphinx, and I don't think we have any way to control or customize that.
---------- nosy: +Mariatta resolution: -> third party status: open -> pending versions: -Python 2.7, Python 3.4, Python 3.5
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Jonathan Fine jfine2358@gmail.com added the comment:
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.)
---------- status: pending -> open
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Ammar Askar ammar@ammaraskar.com added the comment:
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?
---------- nosy: +ammar2
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Jonathan Fine jfine2358@gmail.com added the comment:
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.
---------- title: Docs search does not index glossary -> Docs search does not index glossary items
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Change by Ammar Askar ammar@ammaraskar.com:
---------- keywords: +patch pull_requests: +8248 stage: -> patch review
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Ammar Askar ammar@ammaraskar.com added the comment:
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)
---------- nosy: +berker.peksag
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Jonathan Fine jfine2358@gmail.com added the comment:
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.
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Berker Peksag berker.peksag@gmail.com added the comment:
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.
---------- resolution: third party ->
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Cheryl Sabella cheryl.sabella@gmail.com added the comment:
@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.
---------- nosy: +cheryl.sabella, mdk, willingc versions: -Python 3.6
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Ammar Askar ammar@ammaraskar.com added the comment:
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.
---------- title: Docs search does not index glossary items -> Docs search should prominently show definitions and glossary items
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Julien Palard julien+python@palard.fr added the comment:
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/8c5d0347efd16f16dfb9596715e449cd928...
----------
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
Ammar Askar ammar@ammaraskar.com added the comment:
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 :)
---------- resolution: -> fixed stage: patch review -> resolved status: open -> closed
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue34398 _______________________________________
participants (6)
-
Ammar Askar -
Berker Peksag
-
Cheryl Sabella
-
Jonathan Fine
-
Julien Palard
-
Mariatta Wijaya