setup biothings.web rst documentation

biothings/web/__init__.py

@@ -1,5 +1,5 @@
 """
-    Biothings API
+    Generate a customized BioThings API given a supported database.
 
     biothings.web.connections: Elasticsearch, MongoDB and SQL database access.
     biothings.web.services & query: Data services built on top of connections.

biothings/web/connections.py

@@ -1,4 +1,3 @@
-
 import hashlib
 import logging
 import os
@@ -85,6 +84,15 @@ async def perform_request(
 
 
 def get_es_client(hosts=None, async_=False, **settings):
+    """ Enhanced ES client initialization.
+
+    Additionally support these parameters:
+        async_: use AsyncElasticserach instead of Elasticsearch.
+        aws: setup request signing and provide reasonable ES settings
+            to access AWS OpenSearch, by default assuming it is on HTTPS.
+        sniff: provide resonable default settings to enable client-side
+            LB to an ES cluster. this param itself is not an ES param.
+    """
 
     if settings.pop('aws', False):
         # find region
@@ -107,23 +115,18 @@ def get_es_client(hosts=None, async_=False, **settings):
             region=region, service='es'
         )
 
-        settings.update(
-            http_auth=awsauth, use_ssl=True, verify_certs=True,
-            connection_class=_AsyncConn if async_ else _Conn
-        )
-    # Sniff is only possible if not using the managed cluster
-    # TODO: maybe we won't ever use it
-    # by default we don't do sniffing
-    # if sniff is set, then populate with reasonable defaults unless
-    # explicitly set
+        _cc = _AsyncConn if async_ else _Conn
+        settings.update(http_auth=awsauth, connection_class=_cc)
+        settings.setdefault('use_ssl', True)
+        settings.setdefault('verify_certs', True)
+
+    # not evaluated when 'aws' flag is set because
+    # AWS OpenSearch is internally load-balanced
+    # and does not support client-side sniffing.
     elif settings.pop('sniff', False):
-        _sniff_defaults = {
-            'sniff_on_start': True,
-            'sniff_on_connection_fail': True,
-            'sniffer_timeout': 60,
-        }
-        for setting_name, setting_default in _sniff_defaults.items():
-            settings.setdefault(setting_name, setting_default)
+        settings.setdefault('sniff_on_start', True)
+        settings.setdefault('sniff_on_connection_fail', True)
+        settings.setdefault('sniffer_timeout', 60)
 
     if async_:
         from elasticsearch import AsyncElasticsearch

docs/apidoc/README.md

@@ -0,0 +1,9 @@
+Use sphinx-apidoc to template autodocs.
+Modify the generated documents to match the desired output.
+
+In the future, consider using customized template instead:
+https://github.com/sphinx-doc/sphinx/tree/master/sphinx/templates/apidoc
+to achive one-step solution.
+
+More on:
+https://www.sphinx-doc.org/en/master/man/sphinx-apidoc.html

docs/apidoc/biothings.tests.rst

@@ -0,0 +1,26 @@
+biothings.tests
+===============
+
+.. automodule:: biothings.tests
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+``````````
+
+biothings.tests.hub
+--------------------------
+
+.. automodule:: biothings.tests.hub
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.tests.web
+--------------------------
+
+.. automodule:: biothings.tests.web
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/apidoc/biothings.utils.rst

@@ -0,0 +1,250 @@
+biothings.utils
+===============
+
+.. automodule:: biothings.utils
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+``````````
+
+biothings.utils.aws
+--------------------------
+
+.. automodule:: biothings.utils.aws
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.backend
+------------------------------
+
+.. automodule:: biothings.utils.backend
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.common
+-----------------------------
+
+.. automodule:: biothings.utils.common
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.configuration
+------------------------------------
+
+.. automodule:: biothings.utils.configuration
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.dataload
+-------------------------------
+
+.. automodule:: biothings.utils.dataload
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.diff
+---------------------------
+
+.. automodule:: biothings.utils.diff
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.doc\_traversal
+-------------------------------------
+
+.. automodule:: biothings.utils.doc_traversal
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.docs
+---------------------------
+
+.. automodule:: biothings.utils.docs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.dotfield
+-------------------------------
+
+.. automodule:: biothings.utils.dotfield
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.dotstring
+--------------------------------
+
+.. automodule:: biothings.utils.dotstring
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.es
+-------------------------
+
+.. automodule:: biothings.utils.es
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.exclude\_ids
+-----------------------------------
+
+.. automodule:: biothings.utils.exclude_ids
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.hub
+--------------------------
+
+.. automodule:: biothings.utils.hub
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.hub\_db
+------------------------------
+
+.. automodule:: biothings.utils.hub_db
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.info
+---------------------------
+
+.. automodule:: biothings.utils.info
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.inspect
+------------------------------
+
+.. automodule:: biothings.utils.inspect
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.jsondiff
+-------------------------------
+
+.. automodule:: biothings.utils.jsondiff
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.jsonpatch
+--------------------------------
+
+.. automodule:: biothings.utils.jsonpatch
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.jsonschema
+---------------------------------
+
+.. automodule:: biothings.utils.jsonschema
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.loggers
+------------------------------
+
+.. automodule:: biothings.utils.loggers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.manager
+------------------------------
+
+.. automodule:: biothings.utils.manager
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.mongo
+----------------------------
+
+.. automodule:: biothings.utils.mongo
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.parallel
+-------------------------------
+
+.. automodule:: biothings.utils.parallel
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.parallel\_mp
+-----------------------------------
+
+.. automodule:: biothings.utils.parallel_mp
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.parsers
+------------------------------
+
+.. automodule:: biothings.utils.parsers
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.redis
+----------------------------
+
+.. automodule:: biothings.utils.redis
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.serializer
+---------------------------------
+
+.. automodule:: biothings.utils.serializer
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.shelve
+-----------------------------
+
+.. automodule:: biothings.utils.shelve
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.sqlite3
+------------------------------
+
+.. automodule:: biothings.utils.sqlite3
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.utils.version
+------------------------------
+
+.. automodule:: biothings.utils.version
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/apidoc/biothings.web.analytics.rst

@@ -0,0 +1,34 @@
+biothings.web.analytics
+===============================
+
+.. automodule:: biothings.web.analytics
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Submodules
+``````````
+
+biothings.web.analytics.channels
+---------------------------------------
+
+.. automodule:: biothings.web.analytics.channels
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.web.analytics.events
+-------------------------------------
+
+.. automodule:: biothings.web.analytics.events
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+biothings.web.analytics.notifiers
+----------------------------------------
+
+.. automodule:: biothings.web.analytics.notifiers
+   :members:
+   :undoc-members:
+   :show-inheritance: