1682475 - Show hierarchy of pages in search results as breadcrumbs or similar

Status: NEW

(Developer Infrastructure :: Source Documentation, enhancement)

Description

[Andrew Sutherland [:asuth] (he/him)]

Currently search results only show the name of the page, omitting the hierarchy of the page that would be shown on the page itself via breadcrumbs. This makes it harder to determine whether a search result is relevant without visiting the page. It would be great to display the breadcrumbs like are visible on each page.

For example I searched for mochitests and received results like:

• "Mochitests" which is really Firefox » Firefox Home (New Tab) » Mochitests
• "Tests" which is really Toolkit » Telemetry » Internals » Tests.

Comment 1

[Mahak]

Hi!
I would like to take this as my first issue for outreachy.
Can you elaborate on this more?
Thanks :)

Comment 2

[keiko]

Hello #firefox-source-docs-reviewers

Since it doesn't seems like Mahak is working on this, I would like to take over and try work on this if that is ok.
I am wondering if you could advise me which direction to take.

Checking the code, it is using a template called "sphinx_rtd_theme"
https://searchfox.org/mozilla-central/source/docs/conf.py#100

The search template is provided by
https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/search.html

So I think the possible directions are

1. make a request or change on sphinx_rtd_theme because they are also a open source.
2. create a search template inside 'template' folder specified on conf.py and try to overwrite the theme's template.
   https://searchfox.org/mozilla-central/source/docs/conf.py#72

I personally think it may be beneficial to make a requst on sphinx_rtd_theme so other websites using the theme can also benefit from this addition. Could you share your thoughts on this?

Another question is what kind of format is required for breadcrumbs.
For example, I have been testing on my website to see how I can make the change. Can you please advise if you need the full path?
https://doctest-keiko.readthedocs.io/en/latest/search.html?q=component&check_keywords=yes&area=default#

Many thanks for your help.

Comment 3

[keiko]

Hello #firefox-source-docs-reviewers

Since it doesn't seems like Mahak is working on this, I would like to take over and try work on this if that is ok.
I am wondering if you could advise me which direction to take.

Checking the code, it is using a template called "sphinx_rtd_theme"
https://searchfox.org/mozilla-central/source/docs/conf.py#100

The search template is provided by
https://github.com/readthedocs/sphinx_rtd_theme/blob/master/sphinx_rtd_theme/search.html

So I think the possible directions are

1. make a request or change on sphinx_rtd_theme because they are also a open source.
2. create a search template inside 'template' folder specified on conf.py and try to overwrite the theme's template.
   https://searchfox.org/mozilla-central/source/docs/conf.py#72

I personally think it may be beneficial to make a requst on sphinx_rtd_theme so other websites using the theme can also benefit from this addition. Could you share your thoughts on this?

Another question is what kind of format is required for breadcrumbs.
For example, I have been testing on my website to see how I can make the change. Can you please advise if you need the full path?
https://doctest-keiko.readthedocs.io/en/latest/search.html?q=component&check_keywords=yes&area=default#

Many thanks for your help.

Comment 4

[Andrew Sutherland [:asuth] (he/him)]

(I'm not a reviewer for this code. In terms of breadcrumb format, I think the existing formatting that looks like " » Firefox » Firefox Home (New Tab) » Mochitests" at the top of pages like https://firefox-source-docs.mozilla.org/browser/components/newtab/docs/v2-system-addon/mochitests.html seems to have the appropriate information density.)

Comment 5

[Andrew Halberstadt [:ahal]]

Hi keiko! You are most welcome to work on this. We'll typically not assign bugs until a patch is submitted.

Nice investigation so far. I'd definitely encourage you to attempt to fix this upstream! Though this would likely delay this bug beyond the scope of outreachy (which is totally fine, just worth pointing out). Since sphinx_rtd_theme is probably the most popular theme in the Python ecosystem, your change would benefit a lot of projects out there. That said you might want to double check with the project maintainers before spending too much time on it, there may be technical or principle reasons they wouldn't want to take the change. I'd recommend filing an issue in their tracker and offering to work on it if they would accept it.

That said, you could also attempt to solve this via templating first, since that doesn't need to be blocked by external maintainers. Then if you get it working, the fix would likely be fairly easy to port upstream. This way you can create a PR without too much effort and it's not a big waste of time if they reject it.

(In general this change feels like it should be pretty uncontroversial, but you never know)

Comment 6

[keiko]

Hello Andrew @asuth
Thank you for your help. OK, it will be the full path like, "» Firefox » Firefox Home (New Tab) » Mochitests". I will give it a go. Thanks.

Hello Andrew @ahal
Thank you for the informaton. Yes, your suggestion makes sense. I will try to work on the firefox-source-docs first, given the limited time and possible rejection by them.

I inspected a json file of the results returned by the search function, but they don't include required information for breadcrumbs so in addtion to changing the template, I will probably need to study and tweet how they register a search index.

It seems like a lot more work than I initially anticipated, but I will do my best. Many thanks for your input.