Move implementations into there own sub-sections

Also fixes up some inline-code/examples docs to
correctly display in the generated docs (and
tweaks some URI capitalization).

Change-Id: I001ef2460eb5e9a884ca6db6e8d6f72864191fe7

doc/source/conductors.rst

@@ -65,11 +65,14 @@ Interfaces
 ==========
 
 .. automodule:: taskflow.conductors.base
+.. automodule:: taskflow.conductors.backends
 
 Implementations
 ===============
 
-.. automodule:: taskflow.conductors.backends
+Blocking
+--------
+
 .. automodule:: taskflow.conductors.backends.impl_blocking
 
 Hierarchy

doc/source/engines.rst

@@ -436,10 +436,14 @@ Interfaces
 Implementations
 ===============
 
+.. automodule:: taskflow.engines.action_engine.engine
+
+Components
+----------
+
 .. automodule:: taskflow.engines.action_engine.analyzer
 .. automodule:: taskflow.engines.action_engine.compiler
 .. automodule:: taskflow.engines.action_engine.completer
-.. automodule:: taskflow.engines.action_engine.engine
 .. automodule:: taskflow.engines.action_engine.executor
 .. automodule:: taskflow.engines.action_engine.runner
 .. automodule:: taskflow.engines.action_engine.runtime

doc/source/jobs.rst

@@ -265,6 +265,9 @@ Interfaces
 Implementations
 ===============
 
+Zookeeper
+---------
+
 .. automodule:: taskflow.jobs.backends.impl_zookeeper
 
 Hierarchy

doc/source/persistence.rst

@@ -176,7 +176,7 @@ concept everyone is familiar with).
     See :py:class:`~taskflow.persistence.backends.impl_dir.DirBackend`
     for implementation details.
 
-Sqlalchemy
+SQLAlchemy
 ----------
 
 **Connection**: ``'mysql'`` or ``'postgres'`` or ``'sqlite'``
@@ -288,9 +288,24 @@ Interfaces
 Implementations
 ===============
 
-.. automodule:: taskflow.persistence.backends.impl_dir
+Memory
+------
+
 .. automodule:: taskflow.persistence.backends.impl_memory
+
+Files
+-----
+
+.. automodule:: taskflow.persistence.backends.impl_dir
+
+SQLAlchemy
+----------
+
 .. automodule:: taskflow.persistence.backends.impl_sqlalchemy
+
+Zookeeper
+---------
+
 .. automodule:: taskflow.persistence.backends.impl_zookeeper
 
 Storage

doc/source/workers.rst

@@ -413,10 +413,14 @@ Limitations
   possibly spawn the task on a secondary worker if a timeout is reached (aka
   the first worker has died or has stopped responding).
 
-Interfaces
+Implementations
-==========
+===============
 
 .. automodule:: taskflow.engines.worker_based.engine
+
+Components
+----------
+
 .. automodule:: taskflow.engines.worker_based.proxy
 .. automodule:: taskflow.engines.worker_based.worker
 

taskflow/jobs/backends/__init__.py

@@ -39,17 +39,17 @@ def fetch(name, conf, namespace=BACKEND_NAMESPACE, **kwargs):
 
     NOTE(harlowja): to aid in making it easy to specify configuration and
     options to a board the configuration (which is typical just a dictionary)
-    can also be a uri string that identifies the entrypoint name and any
+    can also be a URI string that identifies the entrypoint name and any
     configuration specific to that board.
 
-    For example, given the following configuration uri:
+    For example, given the following configuration URI::
 
-    zookeeper://<not-used>/?a=b&c=d
+        zookeeper://<not-used>/?a=b&c=d
 
     This will look for the entrypoint named 'zookeeper' and will provide
-    a configuration object composed of the uris parameters, in this case that
+    a configuration object composed of the URI's components, in this case that
-    is {'a': 'b', 'c': 'd'} to the constructor of that board instance (also
+    is ``{'a': 'b', 'c': 'd'}`` to the constructor of that board
-    including the name specified).
+    instance (also including the name specified).
     """
     if isinstance(conf, six.string_types):
         conf = {'board': conf}

taskflow/persistence/backends/__init__.py

@@ -39,16 +39,16 @@ def fetch(conf, namespace=BACKEND_NAMESPACE, **kwargs):
 
     NOTE(harlowja): to aid in making it easy to specify configuration and
     options to a backend the configuration (which is typical just a dictionary)
-    can also be a uri string that identifies the entrypoint name and any
+    can also be a URI string that identifies the entrypoint name and any
     configuration specific to that backend.
 
-    For example, given the following configuration uri:
+    For example, given the following configuration URI::
 
-    mysql://<not-used>/?a=b&c=d
+        mysql://<not-used>/?a=b&c=d
 
     This will look for the entrypoint named 'mysql' and will provide
-    a configuration object composed of the uris parameters, in this case that
+    a configuration object composed of the URI's components, in this case that
-    is {'a': 'b', 'c': 'd'} to the constructor of that persistence backend
+    is ``{'a': 'b', 'c': 'd'}`` to the constructor of that persistence backend
     instance.
     """
     if isinstance(conf, six.string_types):

taskflow/persistence/backends/impl_sqlalchemy.py

@@ -15,8 +15,6 @@
 #    License for the specific language governing permissions and limitations
 #    under the License.
 
-"""Implementation of a SQLAlchemy storage backend."""
-
 from __future__ import absolute_import
 
 import contextlib