Docs (dev): fix server side search (#8845)

Fixed some casing issues, and made the build dir play nice with both
docsets (so we can now build each docset independently).

Closes #8844

Author: stsewd

docs/Makefile

@@ -5,7 +5,7 @@
 SPHINXOPTS    =
 SPHINXBUILD   = sphinx-build
 PAPER         =
-BUILDDIR      = _build
+BUILDDIR      = _build/$(RTD_DOCSET)
 
 # Do not use local Django settings during the docs build
 export DJANGO_SETTINGS_SKIP_LOCAL = True

docs/dev/design/in-doc-search-ui.rst

@@ -49,7 +49,7 @@ Existing Search Implementation
 
 We have a detailed documentation explaining the underlying architecture of our search backend
 and how we index documents to our Elasticsearch index.
-You can read about it :doc:`here <../search>`.
+You can read about it :doc:`here </server-side-search>`.
 
 
 Proposed Architecture for In-Doc Search UI

docs/dev/index.rst

@@ -23,7 +23,7 @@ or taking the open source Read the Docs codebase for your own custom installatio
    docs
    front-end
    i18n
-   search
+   server-side-search
    search-integration
    settings
    tests

docs/dev/search.rst renamed to docs/dev/server-side-search.rst

@@ -1,12 +1,12 @@
-Search
-======
+Server Side Search
+==================
 
 Read The Docs uses Elasticsearch_ instead of the built in Sphinx search for providing better search
 results. Documents are indexed in the Elasticsearch index and the search is made through the API.
 All the Search Code is open source and lives in the `GitHub Repository`_.
 Currently we are using `Elasticsearch 6.3`_.
 
-Local Development Configuration
+Local development configuration
 -------------------------------
 
 Elasticsearch is installed and run as part of the :doc:`development installation guide </install>`.
@@ -24,7 +24,7 @@ management command:
 For performance optimization, we implemented our own version of management command rather than
 the built in management command provided by the `django-elasticsearch-dsl`_ package.
 
-Auto Indexing
+Auto indexing
 ^^^^^^^^^^^^^
 
 By default, Auto Indexing is turned off in development mode. To turn it on, change the
@@ -57,16 +57,12 @@ If you get an error like::
 
    RequestError(400, 'search_phase_execution_exception', 'failed to create query: ...
 
-You can fix this by deleting the page index:
+You can fix this by deleting the page index and :ref:`re-indexing <server-side-search:indexing into elasticsearch>`:
 
 .. prompt:: bash
 
    inv docker.manage 'search_index --delete'
-
-.. note::
-
-   You'll need to :ref:`reindex the projects <search:indexing into elasticsearch>` after this.
-
+   inv docker.manage reindex_elasticsearch
 
 How we index documentations
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -93,7 +89,7 @@ from the main site. We listen to the `post_create` and `post_delete` signals of
 `Project` model and index/delete into Elasticsearch accordingly.
 
 
-Elasticsearch Document
+Elasticsearch document
 ~~~~~~~~~~~~~~~~~~~~~~
 
 `elasticsearch-dsl`_ provides a model-like wrapper for `the Elasticsearch document`_.

tox.ini

@@ -43,7 +43,6 @@ deps =
 setenv =
     RTD_DOCSET=dev
 commands =
-    pip install -r{toxinidir}/requirements/docs.txt  # TODO: Remove this once our Sphinx versions don't conflict
     sphinx-build -W --keep-going -b html -d {envtmpdir}/doctrees . {envtmpdir}/html
 
 [testenv:docs-linkcheck]