Figure out section-based searching

[ericholscher]

It would be neat to be able to search a subset of the docs. An example:

if I did a search at https://docs.readthedocs.io/en/latest/development/install.html -- I had the option to only search inside development inside the docs. This would work similarly well with /guides/ and other "sections".

I think the best option here will be to enable authors to define sections that they want to be able to search within. We have HTMLFile's, so we could see what sections of files users have, and let them create a config that sets these sections as searchable. This could look like:

# .readthedocs.yml

search:
  sections:
    - /development/: Developer docs
    - /guides/: User Guides
 

We could also in theory auto-generate this from the toctree caption argument, or other similar automatic approaches.

@dojutsu-user has an initial demo of this that parses the URL directly from the current page. This is one possible option, but we likely want to let users have a bit more knowledge and UX around sections. Need to think about this more.

[stsewd]

I think we can have a UI element to allow users to filter results, something like:

• files:development/* testing
• version:latest files:guides/* how to test
• title:foo content:bar

I also like the idea of pre-defined sections.

• section:guides version:latest how to break tests

Parsing that expression should be easy, we would need to refactor our search code to create a nice abstraction, but I think it should be fine, the latest thing I did with subprojects wasn't that hard.

[humitos]

Does the backend API support this already? If not, we should open an issue there. On the other hand, if the backend already supports this, we can implement it in the new "Search Addon" from the readthedocs-client.

I agree with @stsewd that this would be better to be done by the user from the UI than specified by the authors of the documentation. I imagine a user can just mark a checkbox saying "Search only under the current section/path/tree" or similar to get results from a subset of the whole documentation.

Even more, those filters could be generated "dynamically" after the results are shown, so the user can narrow down the current query to those sections where there are results.

[stsewd]

Does the backend API support this already?

Nope