Docs: document server side search

docs/features.rst

@@ -61,7 +61,8 @@ When you build your project on RTD, we automatically build a PDF of your project
 Search
 ------
 
-We provide full-text search across all of the pages of documentation hosted on our site. This uses Elasticsearch as the search backend. We hope to be integrating this into the site more fully in the future.
+We provide full-text search across all of the pages of documentation hosted on our site.
+See more are :doc:`/server-side-search`.
 
 Alternate Domains
 -----------------

docs/guides/searching-with-readthedocs.rst

@@ -1,48 +1,20 @@
 Searching with Read the Docs
 ============================
 
-Read the Docs uses Elasticsearch to provide a better search experience.
+Read the Docs uses :doc:`/server-side-search` to provide a better search experience.
 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 in our
-:doc:`Search <../development/search>` docs.
+and how to use advanced query syntax to get more accurate results.
 
+You can find information on the search architecture and how we index documents in our
+:doc:`Search </development/search>` docs.
 
 .. contents:: Table of contents
    :local:
    :backlinks: none
    :depth: 3
 
-
-Improvements over Sphinx search
--------------------------------
-
-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 analytics.
-- Search across multiple projects.
-- Search inside subprojects.
-- Advanced query syntax.
-- Improved search result order.
-- Public search API (documentation pending).
-- Case insensitive search.
-- Results from sections of the documentation.
-- Code search.
-
-
-Search features for project admins
-----------------------------------
-
 Enable "search as you type" in your documentation
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+-------------------------------------------------
 
 `readthedocs-sphinx-search`_ is a Sphinx extension that integrates your
 documentation more closely with the search implementation of Read the Docs.
@@ -54,59 +26,15 @@ you can press :guilabel:`/` (forward slash) and start typing or just visit these
 - https://docs.readthedocs.io/?rtd_search=contributing
 - https://docs.readthedocs.io/?rtd_search=api/v3/projects/
 
-
-Search analytics
-~~~~~~~~~~~~~~~~
-
-Search queries are recorded and 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.
-
-.. figure:: /_static/images/guides/search-analytics-demo.png
-    :width: 40%
-    :align: center
-    :alt: Search analytics in project admin dashboard
-
-    Search analytics demo
-
-
-Search features for readers
----------------------------
-
-Search 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:
-
-- https://readthedocs.org/search/?q=celery&type=project
-- https://readthedocs.org/search/?q=celery._state&type=file
-- https://readthedocs.org/search/?q=celery._state&type=file&project=celery
-- https://readthedocs.org/search/?q=celery._state&type=file&project=celery&version=master
-
-
-Search inside subprojects
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-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 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 the `Simple Query String`_ feature of `Elasticsearch`_.
-This means that as the search query becomes more complex, the results yielded become more specific.
+Read the Docs uses the `Simple Query String`_ feature from `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 ``"`` (double quotes),
 then only those results where the phrase is exactly matched will be returned.
@@ -118,7 +46,7 @@ Example queries:
 - https://docs.readthedocs.io/?rtd_search=%22when%20a%20404%20is%20returned%22
 
 Exact phrase search with slop value
-+++++++++++++++++++++++++++++++++++
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 ``~N`` (tilde N) after a phrase signifies slop amount.
 It can be used to match words that are near one another.
@@ -130,7 +58,7 @@ Example queries:
 - https://docs.readthedocs.io/?rtd_search=%22read%20the%20docs%20story%22~5
 
 Prefix query
-++++++++++++
+~~~~~~~~~~~~
 
 ``*`` (asterisk) at the end of any term signifies a prefix query.
 It returns the results containing the words with specific prefix.
@@ -142,7 +70,7 @@ Example queries:
 - https://docs.readthedocs.io/?rtd_search=build*%20and%20c*%20to%20doc*
 
 Fuzzy query
-+++++++++++
+~~~~~~~~~~~
 
 ``~N`` after a word signifies edit distance (fuzziness).
 This type of query is helpful when the exact spelling of the keyword is unknown.
@@ -155,23 +83,18 @@ Example queries:
 - https://docs.readthedocs.io/?rtd_search=configurtion~1
 
 
-Using the search query syntax to build complex queries
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+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 sections can be used with one another to build complex queries.
 
-Example queries:
+For example:
 
 - https://docs.readthedocs.io/?rtd_search=auto*%20redirect*
 - https://docs.readthedocs.io/?rtd_search=abandon*%20proj*
 - https://docs.readthedocs.io/?rtd_search=localisation~3%20of%20doc*
 
-
+.. _Elasticsearch: https://www.elastic.co/products/elasticsearch
 .. _readthedocs-sphinx-search: https://readthedocs-sphinx-search.readthedocs.io/
-.. _GitHub issues: https://github.com/readthedocs/readthedocs.org/issues/new
-.. _main site search: https://readthedocs.org/search/?q=&type=file&version=latest
-.. _Kombu: http://docs.celeryproject.org/projects/kombu/en/master/
-.. _Celery: http://docs.celeryproject.org/en/master/
 .. _Simple Query String: https://www.elastic.co/guide/en/elasticsearch/reference/current/query-dsl-simple-query-string-query.html#
-.. _Elasticsearch: https://www.elastic.co/products/elasticsearch
 .. _Levenshtein edit distance: https://en.wikipedia.org/wiki/Levenshtein_distance

docs/index.rst

@@ -62,7 +62,8 @@ Learn more about configuring your automated documentation builds
 and some of the core features of Read the Docs.
 
 * **Overview of core features**:
-  :doc:`features`
+  :doc:`features` |
+  :doc:`Server side search </server-side-search>`
 
 * **Configure your documentation**:
   :doc:`Configuration reference <config-file/index>` |
@@ -87,6 +88,7 @@ and some of the core features of Read the Docs.
    :caption: Getting started
 
    features
+   server-side-search
 
    config-file/index
    webhooks

docs/server-side-search.rst

@@ -0,0 +1,48 @@
+Server Side Search
+==================
+
+Read the Docs provides full-text search across all of the pages of all projects,
+this is powered by Elasticsearch_.
+You can search all projects at https://readthedocs.org/search/,
+or search only on your project from the :guilabel:`Search` tab of your project.
+
+We also override the default search engine of your project with our search engine
+to provide you better results within your project.
+
+.. note::
+
+   We fallback to the default search engine from your project
+   if our search engine doesn't return any results.
+
+.. note::
+
+   Currently, we override the default search engine for Sphinx projects only.
+   Mkdocs support will be coming soon!
+
+Improvements
+------------
+
+Some of the improvements from our search engine are:
+
+- Search results include the section where the results come from.
+- Results from :doc:`/subprojects` will be show when searching on the parent project.
+- Special query syntax for more specific results.
+  Like surrounding a term with `"` to have exact matches,
+  see some examples at :ref:`guides/searching-with-readthedocs:search query syntax`.
+
+Analytics
+---------
+
+Know what your users are looking for in your docs.
+To see a list of the top queries and an overview from the last month,
+go to the :guilabel:`Admin` tab of your project,
+and then click on :guilabel:`Search Analytics`.
+
+.. figure:: /_static/images/search-analytics-demo.png
+   :width: 50%
+   :align: center
+   :alt: Search analytics demo
+
+   Search analytics demo
+
+.. _Elasticsearch: https://www.elastic.co/products/elasticsearch