Skip to content

Made syntactical improvments and fixed some vocabulary issues. #6825

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.

Sign up for GitHub

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

Merged
merged 2 commits into from
Apr 21, 2020
Merged

Made syntactical improvments and fixed some vocabulary issues. #6825

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
c0756cc
Made syntactical improvments and fixed some vocabulary issues.
Mar 26, 2020
f5cd306
Apply suggestions from code review
humitos Apr 21, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 32 additions & 39 deletions docs/guides/searching-with-readthedocs.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,11 +2,12 @@ Searching with Read the Docs
============================

Read the Docs uses Elasticsearch to provide a better search experience.
This guide is intended to show that how to add "search as you type" feature to your documentation,
how to use advanced query syntax to get more accurate results and
many other search features that Read the Docs supports with example searches.
This guide explains how to add a "search as you type" feature to your documentation,
how to use advanced query syntax to get more accurate results,
and how to use other search features that Read the Docs supports.
Where appropriate, example searches are provided.

You can find information on the search architecture and how we index document on our
You can find information on the search architecture and how we index document in our
:doc:`Search <../development/search>` docs.


Expand All @@ -19,16 +20,13 @@ You can find information on the search architecture and how we index document on
Improvements over Sphinx search
-------------------------------

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.
Read the Docs supports a powerful documentation search unlike
Sphinx which only have a basic search support.
Sphinx is designed to create a self-contained webpage and all search indexing is performed at the time when the documentation is built.
This means that it is not possible for Sphinx to add features such as searching translations or subprojects or providing analytics on common searches.
Read the Docs supports a powerful documentation search, unlike Sphinx, which has support only for a basic search function.

Features of Read the Docs documentation search are:

- Search as you type feature supported.
- Search-as-you-type feature supported.
- Search analytics.
- Search across multiple projects.
- Search inside subprojects.
Expand All @@ -46,12 +44,12 @@ Search features for project admins
Enable "search as you type" in your documentation
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

`readthedocs-sphinx-search`_ is a Sphinx extension which integrates your
documentation more closely with Read the Docs' search implementation.
It adds a clean and minimal full page search UI which supports **search as you type** feature.
`readthedocs-sphinx-search`_ is a Sphinx extension that integrates your
documentation more closely with the search implementation of Read the Docs.
It adds a clean and minimal full-page search UI that supports a **search as you type** feature.

To get a glimpse of it, you can press :guilabel:`/` (forward slash) and start typing
or just visit these URLs:
To try this feature,
you can press :guilabel:`/` (forward slash) and start typing or just visit these URLs:

- https://docs.readthedocs.io/?rtd_search=contributing
- https://docs.readthedocs.io/?rtd_search=api/v3/projects/
Expand All @@ -60,16 +58,16 @@ or just visit these URLs:
Search analytics
~~~~~~~~~~~~~~~~

Search queries are recorded and are stored in database to provide valuable analytics to the project admins.
These analytics makes it easy to know what your users are looking for in your documentation.
Search queries are recorded are stored in a database in order to provide analytics to the project admins.
These analytics make it easy to know what your users are looking for in your documentation.
You can see these analytics in your project admin dashboard.

.. note::

Currently, this feature is in beta state and is available under a
Currently, this feature is in beta and is available under a
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the feature is enabled by default now, we can remove this note

:ref:`feature flag <guides/feature-flags:Available Flags>`.
We plan to make this available for everyone soon.
If you want to test this feature out and help giving us feedback,
If you want to test this feature and help the project by providing feedback,
please contact us via `GitHub issues`_.

.. figure:: /_static/images/guides/search-analytics-demo.png
Expand All @@ -86,8 +84,7 @@ Search features for readers
Search across all projects
~~~~~~~~~~~~~~~~~~~~~~~~~~

Our `main site search`_ supports searching for projects and
searching across all projects.
Our `main site search`_ supports searching for projects and searching across all projects.
You can also use it to select the specific project and version to narrow down the search results.

Example queries:
Expand All @@ -101,27 +98,25 @@ Example queries:
Search inside subprojects
~~~~~~~~~~~~~~~~~~~~~~~~~

We allow projects to configured as subprojects of another project.
We allow projects to be configured as subprojects of another project.
You can read more about this in our :doc:`Subprojects <../subprojects>` documentation.

If a search is made in a project which have one or more subprojects under it,
the search results then also includes the results from subprojects because
they share a search index with their parent and sibling projects.
For example: `Kombu`_ is one of the subprojects of `Celery`_,
so if you search in Celery docs, then the results from Kombu will also be there.
If a search is made in a project which has one or more subprojects under it,
the search results include the results from those subprojects: projects share search indexes with their parent- and sibling-projects.
For example: If `Kombu`_ is a subproject of `Celery`_ and you search in Celery docs, then the results from Kombu will also be there.
Example: https://docs.celeryproject.org/en/master/search.html?q=utilities&check_keywords=yes&area=default


Search query syntax
~~~~~~~~~~~~~~~~~~~

Read the Docs uses `Simple Query String`_ feature of `Elasticsearch`_,
hence the search query can be made complex to get more accurate results.
Read the Docs uses the `Simple Query String`_ feature of `Elasticsearch`_.
This means that as the search query becomes more complex, the results yielded become more specific.

Exact phrase search
+++++++++++++++++++

If a query is wrapped in ``"``,
If a query is wrapped in ``"`` (double quotes),
then only those results where the phrase is exactly matched will be returned.

Example queries:
Expand All @@ -133,8 +128,8 @@ Example queries:
Exact phrase search with slop value
+++++++++++++++++++++++++++++++++++

``~N`` after a phrase signifies slop amount.
It can be used to match words which are near one another.
``~N`` (tilde N) after a phrase signifies slop amount.
It can be used to match words that are near one another.

Example queries:

Expand All @@ -145,7 +140,7 @@ Example queries:
Prefix query
++++++++++++

``*`` at the end of any term signifies a prefix query.
``*`` (asterisk) at the end of any term signifies a prefix query.
It returns the results containg the words with specific prefix.

Example queries:
Expand All @@ -158,9 +153,8 @@ Fuzzy query
+++++++++++

``~N`` after a word signifies edit distance (fuzziness).
This type of query is helpful when spelling of the actual keyword is unsure.
It returns results that contain terms similar to the search term,
as measured by a `Levenshtein edit distance`_.
This type of query is helpful when the exact spelling of the keyword is unknown.
It returns results that contain terms similar to the search term as measured by a `Levenshtein edit distance`_.

Example queries:

Expand All @@ -172,8 +166,7 @@ Example queries:
Using the search query syntax to build complex queries
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The search query syntaxes described in the previous section
can be used with one another to build complex queries.
The search query syntaxes described in the previous section can be used with one another to build complex queries.

Example queries:

Expand Down