Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add Search Guide #6101

Merged
merged 2 commits into from Sep 9, 2019

Conversation

@dojutsu-user
Copy link
Member

commented Aug 25, 2019

No description provided.

@dojutsu-user dojutsu-user added this to In progress in In-doc search UI via automation Aug 25, 2019
@dojutsu-user

This comment has been minimized.

Copy link
Member Author

commented Aug 26, 2019

This will give desired results after the merging of #5979

@dojutsu-user dojutsu-user requested review from davidfischer and ericholscher and removed request for davidfischer Aug 26, 2019
Copy link
Contributor

left a 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.

docs/guides/searching-with-readthedocs.rst Outdated Show resolved Hide resolved
:depth: 3


Why "Just" Sphinx Search Is Not Enough?

This comment has been minimized.

Copy link
@davidfischer

davidfischer Aug 27, 2019

Contributor

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".

This comment has been minimized.

Copy link
@dojutsu-user

dojutsu-user Aug 28, 2019

Author Member

I copied the same paragraph. It looks better than before.
Thanks.

docs/guides/searching-with-readthedocs.rst Outdated Show resolved Hide resolved
Enable "Search As You Type" In Your Documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`readthedocs-sphinx-search`_ can be used to add a clean and minimal full page search UI

This comment has been minimized.

Copy link
@davidfischer

davidfischer Aug 27, 2019

Contributor

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.

docs/guides/searching-with-readthedocs.rst Outdated Show resolved Hide resolved
docs/guides/searching-with-readthedocs.rst Outdated Show resolved Hide resolved
docs/guides/searching-with-readthedocs.rst Outdated Show resolved Hide resolved
docs/guides/searching-with-readthedocs.rst Outdated Show resolved Hide resolved
docs/guides/searching-with-readthedocs.rst Outdated Show resolved Hide resolved

Features of Read the Docs documentation search are:

- Search as you type feature supported.

This comment has been minimized.

Copy link
@davidfischer

davidfischer Aug 27, 2019

Contributor

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.

This comment has been minimized.

Copy link
@dojutsu-user

dojutsu-user Aug 28, 2019

Author Member

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.

@dojutsu-user dojutsu-user requested a review from davidfischer Aug 28, 2019
@dojutsu-user

This comment has been minimized.

Copy link
Member Author

commented Sep 6, 2019

Example queries are now returning correct results.
External build -- https://external-builds.readthedocs.io/html/docs/6101/guides/searching-with-readthedocs.html

Copy link
Member

left a comment

Similar to the other PR -- I feel this content is better than not having it, so I'm going to merge this. We can build out a proper features section later.

@ericholscher ericholscher merged commit bcafa57 into readthedocs:master Sep 9, 2019
2 checks passed
2 checks passed
continuous-documentation/read-the-docs Read the Docs build succeeded!
Details
continuous-integration/travis-ci/pr The Travis CI build passed
Details
@dojutsu-user dojutsu-user deleted the dojutsu-user:search-guide branch Sep 10, 2019
@dojutsu-user

This comment has been minimized.

Copy link
Member Author

commented Sep 10, 2019

@ericholscher

We can build out a proper features section later.

I am not sure that I followed this.

@dojutsu-user dojutsu-user moved this from In progress to Done in In-doc search UI Oct 3, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
3 participants
You can’t perform that action at this time.