update docs by revising organization and content

biothings/web/__init__.py

@@ -1,9 +1,9 @@
 """
     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.applications: HTTP web application over data services above.
     biothings.web.launcher: Launch web applications in different environments.
+    biothings.web.applications: HTTP web application over data services below.
+    biothings.web.services & query: Data services built on top of connections.
+    biothings.web.connections: Elasticsearch, MongoDB and SQL database access.
     
 """

biothings/web/handlers/services.py

@@ -10,6 +10,13 @@ class StatusHandler(BaseHandler):
     # to sentry monitoring. choose the desired one basing
     # on overall health check architecture.
 
+    # It is technically better to return text or HTML
+    # instead of JSON as this is NOT an API endpoint.
+    # Instead, it's for automated status check, in which
+    # case a simple text response of "OK" suffice, or for
+    # human consumption when "dev" parameter is provided,
+    # in which case an HTML page is more readible.
+
     def head(self):
         return self._check()
 

biothings/web/services/__init__.py

@@ -1,8 +0,0 @@
-# from biothings.web import query
-
-# from an architecture perspective,
-# query module belongs to this module as one of the data services,
-# built on top of the biothings.web.connections layer,
-# however, due to the complexity of the query module,
-# it is put in the same level of this module
-# to simplify the folder structure.

biothings/web/services/query.py

@@ -0,0 +1,11 @@
+"""A Programmatic Query API supporting Biothings Query Syntax.
+
+From an architecture perspective, :py:mod:`biothings.web.query` is one of 
+the data services, built on top of the :py:mod:`biothings.web.connections`
+layer, however, due to the complexity of the module, it is escalated one
+level in organization to simplify the overall folder structure. The features
+are available in `biothings.web.services.query` namespace via import.
+
+"""
+
+from biothings.web.query import *

biothings/web/templates/__init__.py

@@ -0,0 +1,7 @@
+"""
+    The "templates" folder stores HTML templates for native biothings
+    web handlers and is structured as a dummy module to facilitate location
+    resolution. Typically, ``biothings.web.templates.__path__[0]`` returns
+    a string representing the location of this folder on the file system.
+    This folder is intended to be used internally by the SDK developer.
+"""

docs/apidoc/biothings.tests.rst

@@ -6,9 +6,6 @@ biothings.tests
    :undoc-members:
    :show-inheritance:
 
-Submodules
-``````````
-
 biothings.tests.hub
 --------------------------
 

docs/apidoc/biothings.utils.rst

@@ -6,8 +6,6 @@ biothings.utils
    :undoc-members:
    :show-inheritance:
 
-Submodules
-``````````
 
 biothings.utils.aws
 --------------------------

docs/apidoc/biothings.web.analytics.rst

@@ -6,8 +6,6 @@ biothings.web.analytics
    :undoc-members:
    :show-inheritance:
 
-Submodules
-``````````
 
 biothings.web.analytics.channels
 ---------------------------------------

docs/apidoc/biothings.web.applications.rst

@@ -0,0 +1,7 @@
+biothings.web.applications
+===============================
+
+.. automodule:: biothings.web.applications
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/apidoc/biothings.web.connections.rst

@@ -0,0 +1,23 @@
+biothings.web.connections
+===============================
+
+.. automodule:: biothings.web.connections
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Additionally, you can reuse connecions initialized with the same
+parameters by getting it from the connection pools every time.
+Here's the connection pool interface signature:
+
+.. autoclass:: biothings.web.connections._ClientPool
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+The module has already initialized connection pools for each supported
+databases. Directly access these pools without creating by yourselves.
+
+.. autodata:: es
+.. autodata:: sql
+.. autodata:: mongo

docs/apidoc/biothings.web.handlers.rst

@@ -6,8 +6,6 @@ biothings.web.handlers
    :undoc-members:
    :show-inheritance:
 
-Submodules
-``````````
 
 biothings.web.handlers.base
 ----------------------------------

docs/apidoc/biothings.web.launcher.rst

@@ -0,0 +1,7 @@
+biothings.web.launcher
+===============================
+
+.. automodule:: biothings.web.launcher
+   :members:
+   :undoc-members:
+   :show-inheritance:

docs/apidoc/biothings.web.options.rst

@@ -6,16 +6,6 @@ biothings.web.options
    :undoc-members:
    :show-inheritance:
 
-Submodules
-``````````
-
-biothings.web.options.descriptions
------------------------------------------
-
-.. automodule:: biothings.web.options.descriptions
-   :members:
-   :undoc-members:
-   :show-inheritance:
 
 biothings.web.options.manager
 ------------------------------------
@@ -32,11 +22,3 @@ biothings.web.options.openapi
    :members:
    :undoc-members:
    :show-inheritance:
-
-biothings.web.options.swagger
-------------------------------------
-
-.. automodule:: biothings.web.options.swagger
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/apidoc/biothings.web.query.rst

@@ -6,8 +6,6 @@ biothings.web.query
    :undoc-members:
    :show-inheritance:
 
-Submodules
-``````````
 
 biothings.web.query.builder
 ----------------------------------

docs/apidoc/biothings.web.rst

@@ -6,7 +6,19 @@ biothings.web
    :undoc-members:
    :show-inheritance:
 
-Subpackages
+Layers
+-----------
+
+.. toctree::
+   :maxdepth: 4
+
+   biothings.web.launcher
+   biothings.web.applications
+   biothings.web.services
+   biothings.web.connections
+
+
+Components
 -----------
 
 .. toctree::
@@ -16,33 +28,5 @@ Subpackages
    biothings.web.handlers
    biothings.web.options
    biothings.web.query
-   biothings.web.services
    biothings.web.settings
    biothings.web.templates
-
-Submodules
-----------
-
-biothings.web.applications
-``````````````````````````
-
-.. automodule:: biothings.web.applications
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-biothings.web.connections
-`````````````````````````
-
-.. automodule:: biothings.web.connections
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-biothings.web.launcher
-``````````````````````
-
-.. automodule:: biothings.web.launcher
-   :members:
-   :undoc-members:
-   :show-inheritance:

docs/apidoc/biothings.web.services.rst

@@ -6,8 +6,13 @@ biothings.web.services
    :undoc-members:
    :show-inheritance:
 
-Submodules
-``````````
+biothings.web.services.query
+-----------------------------
+
+.. automodule:: biothings.web.services.query
+   :members:
+   :undoc-members:
+   :show-inheritance:
 
 biothings.web.services.health
 -----------------------------

docs/apidoc/biothings.web.settings.rst

@@ -6,8 +6,6 @@ biothings.web.settings
    :undoc-members:
    :show-inheritance:
 
-Submodules
-``````````
 
 biothings.web.settings.configs
 -------------------------------------