Add Search Guide #6101
Add Search Guide #6101
Conversation
|
This will give desired results after the merging of #5979 |
dojutsu-user
added
the
PR: work in progress
dojutsu-user
requested review from
davidfischer and
ericholscher
and removed request for
davidfischer
There was a problem hiding this comment.
This is looking pretty good. I like all the examples of the different kinds of searches. I think that and "how to enable search as you type" are the most important parts of this guide. Perhaps the intro paragraph should reflect that more closely unless you think there are other really important parts to cover.
| :depth: 3 | ||
|
|
||
|
|
||
| Why "Just" Sphinx Search Is Not Enough? |
There was a problem hiding this comment.
I'd rather phrase this as "things Read the Docs adds on top of Sphinx" rather than "Sphinx isn't doing enough". The supporting text can build on that but the title should probably be something like "Improvements over Sphinx search" or something like that.
You could also give a little background in the paragraph on why Sphinx can't do all these improvements. For example, "Sphinx is designed to create a self-contained webpage and all search indexing is done when the documentation is built. As a result, it would be impossible for Sphinx to add features like searching translations or subprojects or having analytics on common searches".
There was a problem hiding this comment.
I copied the same paragraph. It looks better than before.
Thanks.
| Enable "Search As You Type" In Your Documentation | ||
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ | ||
|
|
||
| `readthedocs-sphinx-search`_ can be used to add a clean and minimal full page search UI |
There was a problem hiding this comment.
I think you should just mention that this is a Sphinx extension that integrates documentation more closely with Read the Docs' search implementation. Users familiar with Sphinx will know how to integrate a Sphinx extension and users of MkDocs will know that this is Sphinx only.
|
|
||
| Features of Read the Docs documentation search are: | ||
|
|
||
| - Search as you type feature supported. |
There was a problem hiding this comment.
The order of items in this list should match the next section. Another option is just getting rid of this list since it basically is the next section and you already have the toctree.
There was a problem hiding this comment.
I edited the list to match the order of sections.
I don't want to remove the list completely because it also list out the features which are not explained below in the doc.
|
Example queries are now returning correct results. |
I am not sure that I followed this. |
No description provided.