Updated documentation.

docs/source/_templates/layout.html

@@ -5,7 +5,7 @@
   <style>
     /* Sidebar header (and topbar for mobile) */
     .wy-side-nav-search, .wy-nav-top {
-      background: #405A0F;
+      background: #009BDE;
     }
     /* Sidebar */
     .wy-nav-side {

docs/source/flask.rst

@@ -0,0 +1,80 @@
+.. _elastalk_and_flask:
+
+.. image:: _static/images/logo.svg
+   :width: 100px
+   :alt: elastalk
+   :align: right
+
+.. toctree::
+    :glob:
+
+**********************
+`elastalk` and `Flask`
+**********************
+
+When we built this library we figured you just might want to use it in your
+`Flask <http://flask.pocoo.org/>`_ applications.  With that in mind we've provided a
+few conveniences.
+
+Configuration from Objects
+--------------------------
+
+Flask applications objects support a convention that allows you to configure the application
+using the name of a `Python class <https://docs.python.org/3/tutorial/classes.html>`_ via a method
+on the application's configuration object called
+`from_object() <http://flask.pocoo.org/docs/1.0/config/#configuring-from-files>`_.
+
+Sticking with that convention, the
+:py:class:`ElasticsearchConnection <elastalk.client.ElasticsearchConnection>` in this
+library has :py:attr:`config <elastalk.client.ElasticsearchConnection.config>` attribute
+which returns an :py:class:`ElasticsearchConf <elastalk.config.ElasticsearchConf>`.
+Like the Flask configuration object, this configuration object supports a method called
+:py:func:`from_object <elastalk.config.ElasticsearchConf.from_object>` that mirrors the
+behavior of the Flask method.
+
+Configuration Options
+---------------------
+
+This section describes the configuration options you can use when configuring your Elasticsearch
+settings from an object.
+
+:ESHOSTS: a Python list, or comma-separated string containing the Elasticsearch
+    `seed hosts <https://www.elastic.co/guide/en/elasticsearch/reference/current/modules-discovery-zen.html>`_
+
+    .. seealso::
+
+        :py:attr:`ElasticsearchConf.seeds <elastalk.config.ElasticsearchConf.sniff_on_start>`
+
+:ES_SNIFF_ON_START:  See
+    `Sniffing on startup <https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/sniffing-on-startup.html>`_
+    and :py:attr:`ElasticsearchConf.sniff_on_start <elastalk.config.ElasticsearchConf.sniff_on_start>`
+
+:ES_SNIFF_ON_CONNECTION_FAIL:  See
+    `Sniffing on connection failure <https://www.elastic.co/guide/en/elasticsearch/client/net-api/current/sniffing-on-connection-failure.html>`_
+    and :py:attr:`ElasticsearchConf.sniff_on_connection_fail <elastalk.config.ElasticsearchConf.sniff_on_connection_fail>`
+
+:ES_SNIFFER_TIMEOUT: See
+    `Python Elasticsearch Client <https://elasticsearch-py.readthedocs.io/en/master/index.html?highlight=sniffer_timeout>`_
+    and :py:attr:`ElasticsearchConf.sniffer_timeout <elastalk.config.ElasticsearchConf.sniffer_timeout>`
+
+:ES_MAXSIZE: the maximum number of concurrent connections the client may make
+
+    .. seealso::
+
+        :py:attr:`ElasticsearchConf.maxsize <elastalk.config.ElasticsearchConf.maxsize>`
+
+:ES_MAPPING_FIELD_LIMIT: the maximum number of fields in an index
+
+    .. note::
+
+        Field and object mappings, as well as field aliases count towards this limit.
+
+    .. seealso::
+
+        * :py:attr:`ElasticsearchConf.mapping_field_limit <elastalk.config.ElasticsearchConf.mapping_field_limit>`
+        * `Elasticsearch Mapping <https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html#mapping>`_
+
+
+
+
+

docs/source/getting_started.rst

@@ -12,6 +12,28 @@
 Getting Started
 ***************
 
+Elastic Stack
+-------------
+
+Elasticsearch
+^^^^^^^^^^^^^
+
+You don't need to install `Elasticsearch <https://www.elastic.co/products/elasticsearch>`_ to
+start using this library, but it won't be particularly useful until you start talking to a data
+store.
+
+To get started with Elasticsearch, consult the
+`Elasticsearch docs <https://www.elastic.co/guide/en/elasticsearch/reference/current/getting-started.html>`_.
+
+Kibana
+^^^^^^
+
+You don't absolutely *need* `Kibana <https://www.elastic.co/products/kibana>`_ to get started, but
+if you want a tool to help you inspect and visualize your data, Kibana is for you.
+
+To get started with Kibana, consult the
+`Kibana docs <https://www.elastic.co/guide/en/kibana/current/getting-started.html>`_.
+
 Installing the Library
 ======================
 

docs/source/index.rst

@@ -10,13 +10,15 @@
 elastalk
 ========
 
-Simple Conveniences for Talking to Elasticsearch
+Simple Conveniences for Talking to `Elasticsearch <https://www.elastic.co/products/elasticsearch>`_
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents:
 
    getting_started
+   flask
+   versions
    cli
    api
    development

docs/source/versions.rst

@@ -0,0 +1,27 @@
+.. _versions:
+
+.. image:: _static/images/logo.svg
+   :width: 100px
+   :alt: elastalk
+   :align: right
+
+.. toctree::
+    :glob:
+
+***************************
+`elastalk` Library Versions
+***************************
+
+The `elastalk` version numbers reflect the
+`Elasticsearch <https://www.elastic.co/products/elasticsearch>`_ with which they work.  The
+*major* and *minor* version numbers reflect the Elasticsearch version, while the *patch*
+indicates a revision to the `elastalk` library.
+
+For example, version `6.5.1` is the *first* version of the `elastalk` library (indicated
+by the patch version) built to work with version *6.5* of Elasticsearch.
+
++-----------------------------+------------------------------+
+| `gc_elasticsearch` Version  |    Elasticsearch Version     |
++-----------------------------+------------------------------+
+|         6.5.1               |            6.5               |
++-----------------------------+------------------------------+

elastalk/version.py

@@ -8,5 +8,5 @@
 This module contains project version information.
 """
 
-__version__ = '0.0.2'  #: the working version
-__release__ = '0.0.2'  #: the release version
+__version__ = '6.5.1'  #: the working version
+__release__ = '6.5.1'  #: the release version

setup.py

@@ -8,8 +8,9 @@
 This file is used to create the package we'll publish to PyPI.
 """
 
+import importlib.util
+from pathlib import Path
 import os
-import elastalk
 from setuptools import setup, find_packages, Command
 from codecs import open  # Use a consistent encoding.
 from os import path
@@ -20,8 +21,15 @@
 with open(path.join(here, 'README.rst'), encoding='utf-8') as f:
     long_description = f.read()
 
-# Get the base version from the library.
-version=elastalk.version.__version__
+# Get the base version from the library.  (We'll find it in the `version.py`
+# file in the src directory, but we'll bypass actually loading up the library.)
+vspec = importlib.util.spec_from_file_location(
+  "version",
+  str(Path(__file__).resolve().parent / 'elastalk' / "version.py")
+)
+vmod = importlib.util.module_from_spec(vspec)
+vspec.loader.exec_module(vmod)
+version = getattr(vmod, '__version__')
 
 # If the environment has a build number set...
 if os.getenv('buildnum') is not None: