From 4b047664a346908d69d61805649882f720fe2585 Mon Sep 17 00:00:00 2001
From: Seth Michael Larson <seth.larson@elastic.co>
Date: Mon, 21 Sep 2020 10:32:56 -0500
Subject: [PATCH] Split 'docs/' folder into 'docs/sphinx' and 'docs/guide'

---
 .gitignore                       |   2 +-
 .readthedocs.yml                 |  10 ++
 docs/Changelog.rst               |   1 -
 docs/guide/index.asciidoc        | 155 +++++++++++++++++++++++++++++++
 docs/sphinx/Changelog.rst        |   1 +
 docs/{ => sphinx}/Makefile       |   0
 docs/{ => sphinx}/api.rst        |   0
 docs/{ => sphinx}/async.rst      |   0
 docs/{ => sphinx}/conf.py        |   0
 docs/{ => sphinx}/connection.rst |   0
 docs/{ => sphinx}/exceptions.rst |   0
 docs/{ => sphinx}/helpers.rst    |   0
 docs/{ => sphinx}/index.rst      |   0
 docs/{ => sphinx}/transports.rst |   0
 docs/{ => sphinx}/xpack.rst      |   0
 noxfile.py                       |   2 +-
 16 files changed, 168 insertions(+), 3 deletions(-)
 create mode 100644 .readthedocs.yml
 delete mode 120000 docs/Changelog.rst
 create mode 100644 docs/guide/index.asciidoc
 create mode 120000 docs/sphinx/Changelog.rst
 rename docs/{ => sphinx}/Makefile (100%)
 rename docs/{ => sphinx}/api.rst (100%)
 rename docs/{ => sphinx}/async.rst (100%)
 rename docs/{ => sphinx}/conf.py (100%)
 rename docs/{ => sphinx}/connection.rst (100%)
 rename docs/{ => sphinx}/exceptions.rst (100%)
 rename docs/{ => sphinx}/helpers.rst (100%)
 rename docs/{ => sphinx}/index.rst (100%)
 rename docs/{ => sphinx}/transports.rst (100%)
 rename docs/{ => sphinx}/xpack.rst (100%)

diff --git a/.gitignore b/.gitignore
index 6db331e92..6208cd68e 100644
--- a/.gitignore
+++ b/.gitignore
@@ -69,7 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/sphinx/_build/
 
 # PyBuilder
 .pybuilder/
diff --git a/.readthedocs.yml b/.readthedocs.yml
new file mode 100644
index 000000000..e09a45ed3
--- /dev/null
+++ b/.readthedocs.yml
@@ -0,0 +1,10 @@
+version: 2
+sphinx:
+  configuration: docs/sphinx/conf.py
+
+python:
+  version: 3.7
+  install:
+    - method: pip
+      path: .
+    - requirements: dev-requirements.txt
diff --git a/docs/Changelog.rst b/docs/Changelog.rst
deleted file mode 120000
index bd5ae1633..000000000
--- a/docs/Changelog.rst
+++ /dev/null
@@ -1 +0,0 @@
-../Changelog.rst
\ No newline at end of file
diff --git a/docs/guide/index.asciidoc b/docs/guide/index.asciidoc
new file mode 100644
index 000000000..908cb27d1
--- /dev/null
+++ b/docs/guide/index.asciidoc
@@ -0,0 +1,155 @@
+= elasticsearch-py
+
+== Overview
+
+Official low-level client for Elasticsearch. Its goal is to provide common
+ground for all Elasticsearch-related code in Python; because of this it tries
+to be opinion-free and very extendable. The full documentation is available at
+https://elasticsearch-py.readthedocs.io
+
+=== Installation
+
+It can be installed with pip:
+
+[source,sh]
+-------------------------------------
+$ python -m pip install elasticsearch
+-------------------------------------
+
+If your application uses async/await in Python you can install with
+the `async` extra:
+
+[source,sh]
+--------------------------------------------
+$ python -m pip install elasticsearch[async]
+--------------------------------------------
+
+Read more about https://elasticsearch-py.readthedocs.io/en/master/async.html[how to use asyncio with this project].
+
+
+=== Compatibility
+
+Current development happens in the master branch.
+
+The library is compatible with all Elasticsearch versions since `0.90.x` but you
+**have to use a matching major version**:
+
+For **Elasticsearch 7.0** and later, use the major version 7 (`7.x.y`) of the
+library.
+
+For **Elasticsearch 6.0** and later, use the major version 6 (``6.x.y`) of the
+library.
+
+For **Elasticsearch 5.0** and later, use the major version 5 (`5.x.y`) of the
+library.
+
+For **Elasticsearch 2.0** and later, use the major version 2 (`2.x.y`) of the
+library, and so on.
+
+The recommended way to set your requirements in your `setup.py` or
+`requirements.txt` is::
+
+    # Elasticsearch 7.x
+    elasticsearch>=7,<8
+
+    # Elasticsearch 6.x
+    elasticsearch>=6,<7
+
+    # Elasticsearch 5.x
+    elasticsearch>=5,<6
+
+    # Elasticsearch 2.x
+    elasticsearch>=2,<3
+
+If you have a need to have multiple versions installed at the same time older
+versions are also released as ``elasticsearch2`` and ``elasticsearch5``.
+
+=== Example use
+
+Simple use-case:
+
+[source,python]
+------------------------------------
+>>> from datetime import datetime
+>>> from elasticsearch import Elasticsearch
+
+# By default we connect to localhost:9200
+>>> es = Elasticsearch()
+
+# Datetimes will be serialized...
+>>> es.index(index="my-index-000001", doc_type="test-type", id=42, body={"any": "data", "timestamp": datetime.now()})
+{'_id': '42', '_index': 'my-index-000001', '_type': 'test-type', '_version': 1, 'ok': True}
+
+# ...but not deserialized
+>>> es.get(index="my-index-000001", doc_type="test-type", id=42)['_source']
+{'any': 'data', 'timestamp': '2013-05-12T19:45:31.804229'}
+------------------------------------
+
+[NOTE]
+All the API calls map the raw REST API as closely as possible, including
+the distinction between required and optional arguments to the calls. This
+means that the code makes distinction between positional and keyword arguments;
+we, however, recommend that people use keyword arguments for all calls for
+consistency and safety.
+
+=== Features
+
+The client's features include:
+
+* Translating basic Python data types to and from JSON
+
+* Configurable automatic discovery of cluster nodes
+
+* Persistent connections
+
+* Load balancing (with pluggable selection strategy) across all available nodes
+
+* Failed connection penalization (time based - failed connections won't be
+  retried until a timeout is reached)
+
+* Thread safety
+
+* Pluggable architecture
+
+The client also contains a convenient set of
+https://elasticsearch-py.readthedocs.org/en/master/helpers.html[helpers] for
+some of the more engaging tasks like bulk indexing and reindexing.
+
+
+=== Elasticsearch DSL
+
+For a more high level client library with more limited scope, have a look at
+https://elasticsearch-dsl.readthedocs.org/[elasticsearch-dsl] - a more Pythonic library
+sitting on top of `elasticsearch-py`.
+
+It provides a more convenient and idiomatic way to write and manipulate
+https://elasticsearch-dsl.readthedocs.org/en/latest/search_dsl.html[queries]. It
+stays close to the Elasticsearch JSON DSL, mirroring its terminology and
+structure while exposing the whole range of the DSL from Python either directly
+using defined classes or a queryset-like expressions.
+
+It also provides an optional
+https://elasticsearch-dsl.readthedocs.org/en/latest/persistence.html#doctype[persistence
+layer] for working with documents as Python objects in an ORM-like fashion:
+defining mappings, retrieving and saving documents, wrapping the document data
+in user-defined classes.
+
+
+=== License
+
+Licensed to Elasticsearch B.V. under one or more contributor
+license agreements. See the NOTICE file distributed with
+this work for additional information regarding copyright
+ownership. Elasticsearch B.V. licenses this file to you under
+the Apache License, Version 2.0 (the "License"); you may
+not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing,
+software distributed under the License is distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+KIND, either express or implied.  See the License for the
+specific language governing permissions and limitations
+under the License.
diff --git a/docs/sphinx/Changelog.rst b/docs/sphinx/Changelog.rst
new file mode 120000
index 000000000..6b780f68a
--- /dev/null
+++ b/docs/sphinx/Changelog.rst
@@ -0,0 +1 @@
+../../Changelog.rst
\ No newline at end of file
diff --git a/docs/Makefile b/docs/sphinx/Makefile
similarity index 100%
rename from docs/Makefile
rename to docs/sphinx/Makefile
diff --git a/docs/api.rst b/docs/sphinx/api.rst
similarity index 100%
rename from docs/api.rst
rename to docs/sphinx/api.rst
diff --git a/docs/async.rst b/docs/sphinx/async.rst
similarity index 100%
rename from docs/async.rst
rename to docs/sphinx/async.rst
diff --git a/docs/conf.py b/docs/sphinx/conf.py
similarity index 100%
rename from docs/conf.py
rename to docs/sphinx/conf.py
diff --git a/docs/connection.rst b/docs/sphinx/connection.rst
similarity index 100%
rename from docs/connection.rst
rename to docs/sphinx/connection.rst
diff --git a/docs/exceptions.rst b/docs/sphinx/exceptions.rst
similarity index 100%
rename from docs/exceptions.rst
rename to docs/sphinx/exceptions.rst
diff --git a/docs/helpers.rst b/docs/sphinx/helpers.rst
similarity index 100%
rename from docs/helpers.rst
rename to docs/sphinx/helpers.rst
diff --git a/docs/index.rst b/docs/sphinx/index.rst
similarity index 100%
rename from docs/index.rst
rename to docs/sphinx/index.rst
diff --git a/docs/transports.rst b/docs/sphinx/transports.rst
similarity index 100%
rename from docs/transports.rst
rename to docs/sphinx/transports.rst
diff --git a/docs/xpack.rst b/docs/sphinx/xpack.rst
similarity index 100%
rename from docs/xpack.rst
rename to docs/sphinx/xpack.rst
diff --git a/noxfile.py b/noxfile.py
index 8a9698e60..863926c48 100644
--- a/noxfile.py
+++ b/noxfile.py
@@ -59,4 +59,4 @@ def docs(session):
     session.install(".")
     session.install("-rdev-requirements.txt", "sphinx-rtd-theme")
 
-    session.run("sphinx-build", "docs/", "docs/_build", "-b", "html")
+    session.run("sphinx-build", "docs/sphinx/", "docs/sphinx/_build", "-b", "html")