[7.x] Split 'docs/' folder into 'docs/sphinx' and 'docs/guide'

Co-authored-by: Seth Michael Larson <[email protected]>

.gitignore

@@ -69,7 +69,7 @@ instance/
 .scrapy
 
 # Sphinx documentation
-docs/_build/
+docs/sphinx/_build/
 
 # PyBuilder
 .pybuilder/

.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

docs/Changelog.rst

@@ -1 +0,0 @@
-../Changelog.rst

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.

docs/sphinx/Changelog.rst

@@ -0,0 +1 @@
+../../Changelog.rst

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