Broken search results for internal includes

[ivankravets]

Description of problem

We have received report from our @platformio community that search result for the some pages are broken in our documentation. I tried to look into the source code and found that issue is related with the documents which have internal .. include::.

Steps to Reproduce

1. Open our documentation: http://docs.platformio.org
2. Enter into search form OTA
3. Borken results: http://docs.platformio.org/en/latest/search.html?q=OTA&check_keywords=yes&area=default#

Actual Results

We see 2 broken results with "copyrights" content. Affected RAW files:

• https://github.com/platformio/platformio/blob/develop/docs/history.rst
• https://github.com/platformio/platformio/blob/develop/docs/platforms/espressif.rst
• https://github.com/platformio/platformio/blob/develop/docs/platforms/espressif_extra.rst

Expected Results

Results should contain matched text according to the search query.

[tk0miya]

What did you mean "broken"?
It looks fine for me. each documents includes the keyword OTA.

[ivankravets]

Take a look at the search results

Here are results from the pages which not contain internal .. include::
http://docs.platformio.org/en/latest/search.html?q=MBED+&check_keywords=yes&area=default

[ivankravets]

It looks fine for me. each documents includes the keyword OTA.

Hm... Could you provide me the search output where do you see "OTA"? Thanks.

[tk0miya]

Thank you for explanation. I understand what you said "broken".
Indeed, it does not work well.

At this present, Sphinx uses the source file (*.rst) to display contents around the keyword. So it fails to highlight the keywords if the keyword does not exist in the document directly.
it might be happen when the document is generated by autodoc extension.

I think big change is needed to fix this. It might be generate another text file to show contents around the keyword.

[TimKam]

With #1618, Sphinx is getting the search preview snippets from the HTML files. We can expect this issue to be fixed once 2.0 is released. I will close this issue now.