Improving configuration documentation.

docs/source/blobbing.rst

@@ -19,23 +19,6 @@ If you want to store some (or all) of your seed data as a single
 `base-64 <https://www.base64decode.org/>`_ `BLOB <https://techterms.com/definition/blob>`_, you can
 add a `blobs` key to your :ref:`index configuration file <seed_data_extra_config>`.
 
-Within the `blobs` key you can supply two directives:
-
-    :enabled: *(bool)* `true` to convert seed data to BLOBs
-
-    :exclude: *(list)* a list of top-level keys in your seed data document that should not be
-        included in the BLOB
-
-TODO: Convert to TOML.
-
-.. code-block:: javascript
-
-    {
-      "blobs": {
-        "enabled": true,
-        "exclude": [
-          "firstName",
-          "lastName"
-        ]
-      }
-    }
+You can :ref:`configure <configuration>` blobbing behavior in your
+:py:class:`ElastalkConnection <elastalk.connect.ElastalkConnection>` via the
+:py:class:`ElastalkConf <elastalk.config.ElastalkConf>`.

docs/source/configuration.rst

@@ -12,6 +12,13 @@
 Configuring Your Connection
 ===========================
 
+Configuration from Objects
+--------------------------
+
+If you're wanting to configure your connection from a python object, you're likely using
+:ref:`Flask <elastalk_and_flask>`.  There is another article on that subject called
+:ref:`elastalk_flask_config_from_objects`.
+
 Configuration from TOML
 -----------------------
 
@@ -24,6 +31,8 @@ configure `elastalk` connections using `TOML <https://pypi.org/project/toml/>`_.
 
     -- the TOML project's `README.md <https://github.com/toml-lang/toml>`_
 
+.. _example_toml_configuration:
+
 A Sample TOML Configuration
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -42,28 +51,69 @@ A Sample TOML Configuration
 Options
 ^^^^^^^
 
+    :seeds: a 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:`Elastalk.seeds <elastalk.config.ElastalkConf.sniff_on_start>`
+
+    :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:`ElastalkConf.sniff_on_start <elastalk.config.ElastalkConf.sniff_on_start>`
+
+    :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:`ElastalkConf.sniff_on_connection_fail <elastalk.config.ElastalkConf.sniff_on_connection_fail>`
+
+    :sniffer_timeout: See
+        `Python Elasticsearch Client <https://elasticsearch-py.readthedocs.io/en/master/index.html?highlight=sniffer_timeout>`_
+        and :py:attr:`ElastalkConf.sniffer_timeout <elastalk.config.ElastalkConf.sniffer_timeout>`
+
+    :maxsize: the maximum number of concurrent connections the client may make
+
+        .. seealso::
+
+            :py:attr:`Elastalk.maxsize <elastalk.config.ElastalkConf.maxsize>`
+
+    :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:`ElastalkConf.mapping_field_limit <elastalk.config.ElastalkConf.mapping_field_limit>`
+            * `Elasticsearch Mapping <https://www.elastic.co/guide/en/elasticsearch/reference/current/mapping.html#mapping>`_
+
+.. _configuration_blobs:
+
 blobs
 =====
 
 This section contains global configuration options that control how, when, and which data is
 converted to binary representations (see :ref:`Blobbing <blobbing>`).
 
+    :enabled: indicates whether or not blobbing is enabled
+
     :excluded: the names of attributes that are never included in binary representations when a
         document is packed using the
         :py:func:`ElastalkConnection.pack() <elastalk.connect.ElastalkConnection.pack>`
         method
 
-TODO
+    :key: the key that stores blobbed values in packed documents
 
 indexes
 =======
 
-TODO
-
+This section contains information about specific
+`Elasticsearch Indexes <https://www.elastic.co/blog/what-is-an-elasticsearch-index>`_.  In the
+:ref:`example <example_toml_configuration>` above there are two configured indexes: `cats` and
+`dogs`.  You can configure individual index preferences by adding creating a new section and
+appending the index name to `indexes`.
 
-Configuration from Objects
---------------------------
+    :blobs: index-level blob configuration (See :ref:`configuration_blobs`.)
 
-If you're wanting to configure your connection from a python object, you're likely using
-:ref:`Flask <elastalk_and_flask>`.  There is another article on that subject called
-:ref:`elastalk_flask_config_from_objects`.
+    :mappings: a path to a file that contains an index mapping definition
+        (See :ref:`seed_data_mappings`.)

elastalk/config.py

@@ -244,7 +244,7 @@ def from_object(self, o: str) -> 'ElastalkConf':
         cls = getattr(mod, name_parts[-1])
 
         # Retrieve the hosts (if there are any).
-        es_hosts = getattr(cls, 'ES_HOSTS', None)
+        es_hosts = getattr(cls, 'ES_HOSTS', self.seeds)
         # The seeds might already be a list (if they're defined in code) or
         # they might be expressed as a comma-separated list.  We'll account
         # for both...
@@ -299,6 +299,16 @@ def from_toml(self, toml_: Path or str) -> 'ElastalkConf':
             if isinstance(toml_, Path)
             else toml_
         )
+
+        # Retrieve the hosts (if there are any).
+        _seeds = getattr(_toml, 'seeds', self.seeds)
+        # The seeds might already be a list (if they're defined in code) or
+        # they might be expressed as a comma-separated list.  We'll account
+        # for both...
+        self.seeds = [
+            h.strip() for h in _seeds.split(',')
+        ] if isinstance(_seeds, str) else list(_seeds)
+
         # Let's see if there are any blobbing directives.
         blobs = BlobConf.load(_toml.get('blobs'))
         # If there are...