Adding docs for sdk and integrations

docs/conf.py

@@ -12,12 +12,21 @@
 
 import os
 import sys
+from os import listdir
+from os.path import isdir, join
 
-sys.path[:0] = [
+source_dirs = [
     os.path.abspath("../opentelemetry-api/src/"),
-    os.path.abspath("../ext/opentelemetry-ext-opentracing-shim/src/"),
+    os.path.abspath("../opentelemetry-sdk/src/"),
 ]
 
+ext = "../ext"
+ext_dirs = [
+    os.path.abspath("/".join(["../ext", f, "src"]))
+    for f in listdir(ext)
+    if isdir(join(ext, f))
+]
+sys.path[:0] = source_dirs + ext_dirs
 
 # -- Project information -----------------------------------------------------
 
@@ -64,7 +73,12 @@
 # Sphinx does not recognize generic type TypeVars
 # Container supposedly were fixed, but does not work
 # https://github.com/sphinx-doc/sphinx/pull/3744
-nitpick_ignore = [("py:class", "ValueT"), ("py:class", "typing.Tuple")]
+nitpick_ignore = [
+    ("py:class", "ValueT"),
+    ("py:class", "MetricT"),
+    ("py:class", "typing.Tuple"),
+    ("py:class", "pymongo.monitoring.CommandListener"),
+]
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ["_templates"]

docs/index.rst

@@ -3,24 +3,42 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-OpenTelemetry API
-=================
+OpenTelemetry
+=============
 
-Welcome to OpenTelemetry's API documentation!
+Welcome to OpenTelemetry's documentation!
 
-This documentation describes the ``opentelemetry-api`` package, which provides
-abstract types for OpenTelemetry implementations.
+This documentation describes the ``opentelemetry-api``, ``opentelemetry-sdk``
+and integration packages.
 
 .. toctree::
    :maxdepth: 1
-   :caption: Contents:
+   :caption: OpenTelemetry API:
 
    opentelemetry.context
    opentelemetry.metrics
    opentelemetry.trace
    opentelemetry.util.loader
-   opentelemetry.ext.opentracing_shim
 
+.. toctree::
+    :maxdepth: 1
+    :caption: OpenTelemetry SDK:
+
+    opentelemetry.sdk.context
+    opentelemetry.sdk.metrics
+    opentelemetry.sdk.trace
+
+
+.. toctree::
+    :maxdepth: 1
+    :caption: OpenTelemetry Integrations:
+
+    opentelemetry.ext.flask
+    opentelemetry.ext.http_requests
+    opentelemetry.ext.jaeger
+    opentelemetry.ext.opentracing_shim
+    opentelemetry.ext.pymongo
+    opentelemetry.ext.wsgi
 
 Indices and tables
 ==================

docs/opentelemetry.ext.flask.rst

@@ -0,0 +1,10 @@
+opentelemetry.ext.flask package
+==========================================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.ext.flask
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.ext.http_requests.rst

@@ -0,0 +1,10 @@
+opentelemetry.ext.http_requests package
+==========================================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.ext.http_requests
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.ext.jaeger.gen.jaeger.ttypes.rst

@@ -0,0 +1,11 @@
+opentelemetry.ext.jaeger.gen.jaeger.ttypes
+==========================================
+
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.ext.jaeger.gen.jaeger.ttypes
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.ext.jaeger.rst

@@ -0,0 +1,19 @@
+opentelemetry.ext.jaeger package
+==========================================
+
+
+Submodules
+----------
+
+.. toctree::
+
+   opentelemetry.ext.jaeger.gen.jaeger.ttypes
+
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.ext.jaeger
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.ext.pymongo.rst

@@ -0,0 +1,10 @@
+opentelemetry.ext.pymongo package
+==========================================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.ext.pymongo
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.ext.wsgi.rst

@@ -0,0 +1,10 @@
+opentelemetry.ext.wsgi package
+==========================================
+
+Module contents
+---------------
+
+.. automodule:: opentelemetry.ext.wsgi
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.sdk.context.rst

@@ -0,0 +1,7 @@
+opentelemetry.sdk.context
+==========================================
+
+.. automodule:: opentelemetry.sdk.context
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.sdk.metrics.rst

@@ -0,0 +1,7 @@
+opentelemetry.sdk.metrics package
+==========================================
+
+.. automodule:: opentelemetry.sdk.metrics
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.sdk.trace.export.rst

@@ -0,0 +1,7 @@
+opentelemetry.sdk.trace.export
+==========================================
+
+.. automodule:: opentelemetry.sdk.trace.export
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.sdk.trace.rst

@@ -0,0 +1,14 @@
+opentelemetry.sdk.trace package
+==========================================
+
+Submodules
+----------
+
+.. toctree::
+
+   opentelemetry.sdk.trace.export
+
+.. automodule:: opentelemetry.sdk.trace
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/opentelemetry.trace.rst

@@ -6,9 +6,10 @@ Submodules
 
 .. toctree::
 
+   opentelemetry.trace.sampling
    opentelemetry.trace.status
 
 Module contents
 ---------------
 
-.. automodule:: opentelemetry.trace
+.. automodule:: opentelemetry.trace

docs/opentelemetry.trace.sampling.rst

@@ -0,0 +1,7 @@
+opentelemetry.trace.sampling
+============================
+
+.. automodule:: opentelemetry.trace.sampling
+    :members:
+    :undoc-members:
+    :show-inheritance:

ext/opentelemetry-ext-opentracing-shim/src/opentelemetry/ext/opentracing_shim/__init__.py

@@ -303,27 +303,30 @@ class ScopeShim(opentracing.Scope):
 
     It is necessary to have both ways for constructing `ScopeShim` objects
     because in some cases we need to create the object from an OpenTelemetry
-    `Span` context manager (as returned by
+    `opentelemetry.trace.Span` context manager (as returned by
     :meth:`opentelemetry.trace.Tracer.use_span`), in which case our only way of
-    retrieving a `Span` object is by calling the ``__enter__()`` method on the
-    context manager, which makes the span active in the OpenTelemetry tracer;
-    whereas in other cases we need to accept a `SpanShim` object and wrap it in
-    a `ScopeShim`. The former is used mainly when the instrumentation code
-    retrieves the currently-active span using `ScopeManagerShim.active`. The
-    latter is mainly used when the instrumentation code activates a span using
+    retrieving a `opentelemetry.trace.Span` object is by calling the
+    ``__enter__()`` method on the context manager, which makes the span active
+    in the OpenTelemetry tracer; whereas in other cases we need to accept a
+    `SpanShim` object and wrap it in a `ScopeShim`. The former is used mainly
+    when the instrumentation code retrieves the currently-active span using
+    `ScopeManagerShim.active`. The latter is mainly used when the
+    instrumentation code activates a span using
     :meth:`ScopeManagerShim.activate`.
 
     Args:
         manager: The :class:`ScopeManagerShim` that created this
             :class:`ScopeShim`.
         span: The :class:`SpanShim` this :class:`ScopeShim` controls.
         span_cm(:class:`contextlib.AbstractContextManager`, optional): A
-            Python context manager which yields an OpenTelemetry `Span` from
-            its ``__enter__()`` method. Used by :meth:`from_context_manager` to
-            store the context manager as an attribute so that it can later be
-            closed by calling its ``__exit__()`` method. Defaults to `None`.
-
-    TODO: Is :class:`contextlib.AbstractContextManager` the correct type for *span_cm*?
+            Python context manager which yields an OpenTelemetry
+            `opentelemetry.trace.Span` from its ``__enter__()`` method. Used
+            by :meth:`from_context_manager` to store the context manager as
+            an attribute so that it can later be closed by calling its
+            ``__exit__()`` method. Defaults to `None`.
+
+    TODO: Is :class:`contextlib.AbstractContextManager` the correct
+          type for *span_cm*?
     """
 
     def __init__(self, manager, span, span_cm=None):
@@ -334,12 +337,13 @@ def __init__(self, manager, span, span_cm=None):
     # need to get rid of `manager.tracer` for this.
     @classmethod
     def from_context_manager(cls, manager, span_cm):
-        """Constructs a :class:`ScopeShim` from an OpenTelemetry `Span` context
+        """Constructs a :class:`ScopeShim` from an OpenTelemetry
+        `opentelemetry.trace.Span` context
         manager.
 
-        The method extracts a `Span` object from the context manager by calling
-        the context manager's ``__enter__()`` method. This causes the span to
-        start in the OpenTelemetry tracer.
+        The method extracts a `opentelemetry.trace.Span` object from the
+        context manager by calling the context manager's ``__enter__()``
+        method. This causes the span to start in the OpenTelemetry tracer.
 
         Example usage::
 
@@ -353,7 +357,7 @@ def from_context_manager(cls, manager, span_cm):
         Args:
             manager: The :class:`ScopeManagerShim` that created this
                 :class:`ScopeShim`.
-            span_cm: An OpenTelemetry `Span` context manager as returned by
+            span_cm: A context manager as returned by
                 :meth:`opentelemetry.trace.Tracer.use_span`.
         """
 
@@ -396,7 +400,7 @@ def close(self):
 
 class ScopeManagerShim(opentracing.ScopeManager):
     """Implements :class:`opentracing.ScopeManager` by setting and getting the
-    active `Span` in the OpenTelemetry tracer.
+    active `opentelemetry.trace.Span` in the OpenTelemetry tracer.
 
     This class keeps a reference to a :class:`TracerShim` as an attribute. This
     reference is used to communicate with the OpenTelemetry tracer. It is

ext/opentelemetry-ext-pymongo/src/opentelemetry/ext/pymongo/__init__.py

@@ -42,6 +42,7 @@ def __init__(self, tracer):
         self._span_dict = {}
 
     def started(self, event: monitoring.CommandStartedEvent):
+        """ Method to handle a pymongo CommandStartedEvent """
         command = event.command.get(event.command_name, "")
         name = DATABASE_TYPE + "." + event.command_name
         statement = event.command_name
@@ -77,6 +78,7 @@ def started(self, event: monitoring.CommandStartedEvent):
                 self._remove_span(event)
 
     def succeeded(self, event: monitoring.CommandSucceededEvent):
+        """ Method to handle a pymongo CommandSucceededEvent """
         span = self._get_span(event)
         if span is not None:
             span.set_attribute(
@@ -87,6 +89,7 @@ def succeeded(self, event: monitoring.CommandSucceededEvent):
             self._remove_span(event)
 
     def failed(self, event: monitoring.CommandFailedEvent):
+        """ Method to handle a pymongo CommandFailedEvent """
         span = self._get_span(event)
         if span is not None:
             span.set_attribute(

opentelemetry-api/src/opentelemetry/trace/sampling.py

@@ -24,8 +24,8 @@ class Decision:
     """A sampling decision as applied to a newly-created Span.
 
     Args:
-        sampled: Whether the `Span` should be sampled.
-        attributes: Attributes to add to the `Span`.
+        sampled: Whether the `opentelemetry.trace.Span` should be sampled.
+        attributes: Attributes to add to the `opentelemetry.trace.Span`.
     """
 
     def __repr__(self) -> str:

opentelemetry-sdk/src/opentelemetry/sdk/__init__.py

@@ -12,6 +12,10 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+"""
+The OpenTelemetry SDK package is an implementation of the OpenTelemetry
+API
+"""
 from . import metrics, trace, util
 
 __all__ = ["metrics", "trace", "util"]

opentelemetry-sdk/src/opentelemetry/sdk/metrics/__init__.py

@@ -24,7 +24,7 @@
 
 # pylint: disable=redefined-outer-name
 class LabelSet(metrics_api.LabelSet):
-    """See `opentelemetry.metrics.LabelSet."""
+    """See `opentelemetry.metrics.LabelSet`."""
 
     def __init__(self, labels: Dict[str, str] = None):
         self.labels = labels