New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Docs search should prominently show definitions and glossary items #78579
Comments
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 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." |
Hmm the search is built-in functionality in Sphinx, and I don't think we have any way to control or customize that. |
Good discovery. The glossary uses the RST glossary directive. The Sphinx docs have a glossary, which is indexed by its search. 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.) |
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? |
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. 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 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. |
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) |
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. |
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. |
@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. |
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. |
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 :) |
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:
bugs.python.org fields:
The text was updated successfully, but these errors were encountered: