Opened 4 years ago
Last modified 3 years ago
#26104 new defect
HTML results for search_doc and search_src in Jupyter Notebook
Reported by: | embray | Owned by: | |
---|---|---|---|
Priority: | major | Milestone: | sage-pending |
Component: | notebook | Keywords: | jupyter |
Cc: | zerline, nthiery, jhpalmieri | Merged in: | |
Authors: | Reviewers: | ||
Report Upstream: | N/A | Work issues: | |
Branch: | Commit: | ||
Dependencies: | Stopgaps: |
Description (last modified by )
As pointed out in comment:4:ticket:24784, the search_doc
and search_src
functions, when run in the legacy Sage Notebook, produce HTML-formatted results, with working links to all the doc pages/source code containing search hits.
However, the Jupyter Notebook just displays the plain-text search results. As I pointed out in #24784, it is possible to return HTML-formatted results to Jupyter as well, in a mime-bundle. Jupyter will then determine which format to use depending on the context: plain text, or HTML, with a preference for HTML in the notebook.
This is easily fixed as demonstrated in the fix for #24784, but there are a few problems with the current HTML result formatting:
- Most importantly, it produces URLs to search results that only work in the legacy notebook (which has its own URLs for hosting the Sage docs).
Instead, I would propose that it produce links to doc.sagemath.org by default, but also have an optionalAs mentioned below, we don't need this because we can serve the docs throughoffline=True
option to producefile:///
URLs if the docs are available offline. The reason for makingoffline=False
by default is that when running the Jupyter Notebook in a cloud-based setting, such as mybinder.org, producingfile:///
links would not be useful./kernelspec/sagemath/doc
. However, this should probably still check that the docs are installed locally so that they can be served by Jupyter. If not, it would still make sense to fall back on doc.sagemath.org.
- The HTML that is currently output is very "web 1.0", using tags and features that are deprecated in HTML5. The output could easily be updated to modern HTML5 + CSS.
- The output is also not very helpful. It simply displays links to the documentation pages in which results were found, but does not display the search results themselves. It would be easy, for each document in which there are results, to display the result snippets inline, perhaps with the search terms highlighted.
- When linking to Sphinx docs it would also be good to include the
highlight=
query string parameter, in order to highlight the search term(s) in the page.
Change History (10)
comment:1 Changed 4 years ago by
comment:2 follow-up: ↓ 4 Changed 4 years ago by
I think that in the past, people have also considered using Sphinx's search capabilities in search_doc
, to get nicely formatted results with highlighted terms, etc. I don't think there was a ticket for this, but it might be something to consider.
comment:3 Changed 4 years ago by
Oh, I was wondering if it were possible to serve kernel-specific URLs. That solves that.
comment:4 in reply to: ↑ 2 Changed 4 years ago by
Replying to jhpalmieri:
I think that in the past, people have also considered using Sphinx's search capabilities in
search_doc
, to get nicely formatted results with highlighted terms, etc. I don't think there was a ticket for this, but it might be something to consider.
If nothing else I'm surprised we aren't using Sphinx's search indices.
comment:5 Changed 4 years ago by
- Description modified (diff)
comment:6 follow-up: ↓ 7 Changed 4 years ago by
However, this should probably still check that the docs are installed locally so that they can be served by Jupyter. If not, it would still make sense to fall back on doc.sagemath.org.
Shall we go this way (it would indeed be nice to the user), it would be best to use the same logic for the Help menu. That is, have somewhere a "base_url_of_sage_doc()" that would take into account the presence of locally built doc and whether we are being served through a Jupyter kernel, or not; and use it in both places (and maybe elsewhere too).
comment:7 in reply to: ↑ 6 Changed 4 years ago by
Replying to nthiery:
However, this should probably still check that the docs are installed locally so that they can be served by Jupyter. If not, it would still make sense to fall back on doc.sagemath.org.
Shall we go this way (it would indeed be nice to the user), it would be best to use the same logic for the Help menu. That is, have somewhere a "base_url_of_sage_doc()" that would take into account the presence of locally built doc and whether we are being served through a Jupyter kernel, or not; and use it in both places (and maybe elsewhere too).
I agree, it would be good to have a generic, reusable utility function to get the best available URL for the sage docs in any given context.
comment:8 Changed 4 years ago by
- Milestone changed from sage-8.4 to sage-8.5
comment:9 Changed 4 years ago by
- Milestone changed from sage-8.5 to sage-8.7
Retargeting some of my tickets (somewhat optimistically for now).
comment:10 Changed 3 years ago by
- Milestone changed from sage-8.7 to sage-pending
Removing most of the rest of my open tickets out of the 8.7 milestone, which should be closed.
For info: assuming the Sage documentation has been compiled, it's possible to access it through the relative URL
/kernelspecs/sagemath/doc/
. That's how theHelp-> Reference Manual
menu item and friends in the Jupyter notebook points to the documentation, and it works regardless of where the Jupyter server is running (locally, on binder, ...).This should resolve the
file://
dilemma. Well, again assuming that the doc is compiled; I don't know how strong an assumption this is. Somehow, theHelp
menu already makes that assumption, so presumably it's reasonable to make the same one elsewhere in Jupyter.