Fix some v2.0.0 docs

CHANGELOG.rst

@@ -27,7 +27,7 @@ History
 1.2.1 (2016-09-22)
 ------------------
 
-- Make Span.log(self, **kwargs) smarter
+- Make Span.log(self, \**kwargs) smarter
 
 
 1.2.0 (2016-09-21)
@@ -115,7 +115,7 @@ History
 ------------------
 
 - Change inheritance to match api-go: TraceContextSource extends codecs,
-Tracer extends TraceContextSource
+  Tracer extends TraceContextSource
 - Create API harness
 
 

docs/conf.py

@@ -16,7 +16,7 @@
 
 html_theme = 'sphinx_rtd_theme'
 html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
-html_static_path = ['_static']
+html_static_path = []
 exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
 
 intersphinx_mapping = {

opentracing/propagation.py

@@ -25,7 +25,7 @@ class UnsupportedFormatException(Exception):
     """UnsupportedFormatException should be used when the provided format
     value is unknown or disallowed by the Tracer.
 
-    See Tracer.inject() and Tracer.extract().
+    See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`.
     """
     pass
 
@@ -34,7 +34,7 @@ class InvalidCarrierException(Exception):
     """InvalidCarrierException should be used when the provided carrier
     instance does not match what the `format` argument requires.
 
-    See Tracer.inject() and Tracer.extract().
+    See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`.
     """
     pass
 
@@ -43,16 +43,16 @@ class SpanContextCorruptedException(Exception):
     """SpanContextCorruptedException should be used when the underlying span
     context state is seemingly present but not well-formed.
 
-    See Tracer.inject() and Tracer.extract().
+    See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`.
     """
     pass
 
 
 class Format(object):
     """A namespace for builtin carrier formats.
 
-    These static constants are intended for use in the Tracer.inject() and
-    Tracer.extract() methods. E.g.::
+    These static constants are intended for use in the :meth:`Tracer.inject()`
+    and :meth:`Tracer.extract()` methods. E.g.::
 
         tracer.inject(span.context, Format.BINARY, binary_carrier)
 
@@ -62,9 +62,9 @@ class Format(object):
     """
     The BINARY format represents SpanContexts in an opaque bytearray carrier.
 
-    For both Tracer.inject() and Tracer.extract() the carrier should be a
-    bytearray instance. Tracer.inject() must append to the bytearray carrier
-    (rather than replace its contents).
+    For both :meth:`Tracer.inject()` and :meth:`Tracer.extract()` the carrier
+    should be a bytearray instance. :meth:`Tracer.inject()` must append to the
+    bytearray carrier (rather than replace its contents).
     """
 
     TEXT_MAP = 'text_map'

opentracing/scope.py

@@ -24,17 +24,17 @@
 class Scope(object):
     """A `Scope` formalizes the activation and deactivation of a `Span`,
     usually from a CPU standpoint. Many times a `Span` will be extant (in that
-    `Span#finish()` has not been called) despite being in a non-runnable state
-    from a CPU/scheduler standpoint. For instance, a `Span` representing the
-    client side of an RPC will be unfinished but blocked on IO while the RPC is
-    still outstanding. A `Scope` defines when a given `Span` is scheduled
-    and on the path.
+    :meth:`Span.finish()` has not been called) despite being in a non-runnable
+    state from a CPU/scheduler standpoint. For instance, a ``Span``
+    representing the client side of an RPC will be unfinished but blocked on IO
+    while the RPC is still outstanding. A ``Scope`` defines when a given
+    ``Span`` is scheduled and on the path.
     """
     def __init__(self, manager, span):
-        """Initializes a `Scope` for the given `Span` object.
+        """Initializes a ``Scope`` for the given ``Span`` object.
 
-        :param manager: the `ScopeManager` that created this `Scope`
-        :param span: the `Span` used for this `Scope`
+        :param manager: the ``ScopeManager`` that created this ``Scope``
+        :param span: the ``Span`` used for this ``Scope``
         """
         self._manager = manager
         self._span = span

opentracing/scope_manager.py

@@ -26,8 +26,8 @@
 
 class ScopeManager(object):
     """The `ScopeManager` interface abstracts both the activation of `Span`
-    instances (via `ScopeManager#activate(span, finish_on_close)`) and
-    access to an active `Span` / `Scope` (via `ScopeManager#active`).
+    instances (via :meth:`ScopeManager.activate()`) and access to an active
+    `Span` / `Scope` (via :meth:`ScopeManager.active`).
     """
     def __init__(self):
         # TODO: `tracer` should not be None, but we don't have a reference;
@@ -41,22 +41,22 @@ def activate(self, span, finish_on_close):
 
         :param span: the `Span` that should become active.
         :param finish_on_close: whether span should be automatically
-            finished when `Scope#close()` is called.
+            finished when :meth:`Scope.close()` is called.
 
         :return: a `Scope` instance to control the end of the active period for
             the `Span`. It is a programming error to neglect to call
-            `Scope#close()` on the returned instance.
+            :meth:`Scope.close()` on the returned instance.
         """
         return self._noop_scope
 
     @property
     def active(self):
         """Returns the currently active `Scope` which can be used to access the
-        currently active `Scope#span`.
+        currently active `Scope.span`.
 
         If there is a non-null `Scope`, its wrapped `Span` becomes an implicit
-        parent of any newly-created `Span` at `Tracer#start_active_span()`
-        time.
+        parent of any newly-created `Span` at
+        :meth:`Tracer.start_active_span()` time.
 
         :return: the `Scope` that is active, or `None` if not available.
         """

opentracing/span.py

@@ -28,10 +28,10 @@ class SpanContext(object):
     Spans and across process boundaries.
 
     SpanContext is logically divided into two pieces: the user-level "Baggage"
-    (see set_baggage_item and get_baggage_item) that propagates across Span
-    boundaries and any Tracer-implementation-specific fields that are needed to
-    identify or otherwise contextualize the associated Span instance (e.g., a
-    <trace_id, span_id, sampled> tuple).
+    (see :meth:`Span.set_baggage_item` and :meth:`Span.get_baggage_item`) that
+    propagates across Span boundaries and any Tracer-implementation-specific
+    fields that are needed to identify or otherwise contextualize the
+    associated Span instance (e.g., a <trace_id, span_id, sampled> tuple).
     """
 
     EMPTY_BAGGAGE = {}  # TODO would be nice to make this immutable
@@ -44,10 +44,11 @@ def baggage(self):
 
         The caller must not modify the returned dictionary.
 
-        See also: Span.set_baggage_item() / Span.get_baggage_item()
+        See also: :meth:`Span.set_baggage_item()` /
+        :meth:`Span.get_baggage_item()`
 
         :rtype: dict
-        :return: returns baggage associated with this SpanContext or {}.
+        :return: baggage associated with this SpanContext or {}.
         """
         return SpanContext.EMPTY_BAGGAGE
 
@@ -60,14 +61,13 @@ class Span(object):
     and these relationships transitively form a DAG. It is common for spans to
     have at most one parent, and thus most traces are merely tree structures.
 
-    Span implements a Context Manager API that allows the following usage:
-
-    .. code-block:: python
+    Span implements a Context Manager API that allows the following usage::
 
         with tracer.start_span(operation_name='go_fishing') as span:
             call_some_service()
 
-    In the Context Manager syntax it's not necessary to call span.finish()
+    In the Context Manager syntax it's not necessary to call
+    :meth:`Span.finish()`
     """
 
     def __init__(self, tracer, context):
@@ -81,23 +81,23 @@ def context(self):
         The SpanContext contains state that propagates from Span to Span in a
         larger trace.
 
-        :return: returns the SpanContext associated with this Span.
+        :return: the SpanContext associated with this Span.
         """
         return self._context
 
     @property
     def tracer(self):
         """Provides access to the Tracer that created this Span.
 
-        :return: returns the Tracer that created this Span.
+        :return: the Tracer that created this Span.
         """
         return self._tracer
 
     def set_operation_name(self, operation_name):
         """Changes the operation name.
 
         :param operation_name: the new operation name
-        :return: Returns the Span itself, for call chaining.
+        :return: the Span itself, for call chaining.
         """
         return self
 
@@ -126,8 +126,8 @@ def set_tag(self, key, value):
         :param key: key or name of the tag. Must be a string.
         :param value: value of the tag.
 
-        :return: Returns the Span itself, for call chaining.
         :rtype: Span
+        :return: the Span itself, for call chaining.
         """
         return self
 
@@ -149,8 +149,8 @@ def log_kv(self, key_values, timestamp=None):
             None
         :type timestamp: float
 
-        :return: Returns the Span itself, for call chaining.
         :rtype: Span
+        :return: the Span itself, for call chaining.
         """
         return self
 
@@ -173,7 +173,7 @@ def set_baggage_item(self, key, value):
         :param value: Baggage item value
         :type value: str
 
-        :rtype : Span
+        :rtype: Span
         :return: itself, for chaining the calls.
         """
         return self
@@ -184,15 +184,15 @@ def get_baggage_item(self, key):
         :param key: key of the Baggage item
         :type key: str
 
-        :rtype : str
+        :rtype: str
         :return: value of the Baggage item with given key, or None.
         """
         return None
 
     def __enter__(self):
         """Invoked when span is used as a context manager.
 
-        :return: returns the Span itself
+        :return: the Span itself
         """
         return self
 

opentracing/tracer.py

@@ -57,7 +57,7 @@ def active_span(self):
         Tracer.scope_manager.active.span, and None will be returned if
         Scope.span is None.
 
-        :return: returns the active Span.
+        :return: the active Span.
         """
         scope = self._scope_manager.active
         return None if scope is None else scope.span
@@ -72,7 +72,7 @@ def start_active_span(self,
                           finish_on_close=True):
         """Returns a newly started and activated `Scope`.
 
-        The returned `Scope` supports with-statement contexts. For example:
+        The returned `Scope` supports with-statement contexts. For example::
 
             with tracer.start_active_span('...') as scope:
                 scope.span.set_tag('http.method', 'GET')
@@ -81,7 +81,7 @@ def start_active_span(self,
             # the with statement.
 
         It's also possible to not finish the `Span` when the `Scope` context
-        expires:
+        expires::
 
             with tracer.start_active_span('...',
                                           finish_on_close=False) as scope:
@@ -108,7 +108,7 @@ def start_active_span(self,
         :param finish_on_close: whether span should automatically be finished
             when `Scope#close()` is called.
 
-         :return: a `Scope`, already registered via the `ScopeManager`.
+        :return: a `Scope`, already registered via the `ScopeManager`.
         """
         return self._noop_scope
 
@@ -127,7 +127,7 @@ def start_span(self,
             tracer.start_span('...')
 
 
-        Starting a child Span (see also start_child_span())::
+        Starting a child Span (see also `start_child_span()`)::
 
             tracer.start_span(
                 '...',
@@ -157,7 +157,7 @@ def start_span(self,
         :param ignore_active_span: an explicit flag that ignores the current
             active `Scope` and creates a root `Span`.
 
-        :return: Returns an already-started Span instance.
+        :return: an already-started Span instance.
         """
         return self._noop_span
 
@@ -192,9 +192,9 @@ def extract(self, format, carrier):
         Implementations MUST raise opentracing.UnsupportedFormatException if
         `format` is unknown or disallowed.
 
-        Implementations may raise opentracing.InvalidCarrierException,
-        opentracing.SpanContextCorruptedException, or implementation-specific
-        errors if there are problems with `carrier`.
+        Implementations may raise :meth:`opentracing.InvalidCarrierException`,
+        :meth:`opentracing.SpanContextCorruptedException`, or
+        implementation-specific errors if there are problems with `carrier`.
 
         :param format: a python object instance that represents a given
             carrier format. `format` may be of any type, and `format` equality
@@ -224,13 +224,13 @@ class ReferenceType(object):
 class Reference(namedtuple('Reference', ['type', 'referenced_context'])):
     """A Reference pairs a reference type with a referenced SpanContext.
 
-    References are used by Tracer.start_span() to describe the relationships
-    between Spans.
+    References are used by :meth:`Tracer.start_span()` to describe the
+    relationships between Spans.
 
     Tracer implementations must ignore references where referenced_context is
     None.  This behavior allows for simpler code when an inbound RPC request
-    contains no tracing information and as a result tracer.extract() returns
-    None::
+    contains no tracing information and as a result :meth:`Tracer.extract()`
+    returns None::
 
         parent_ref = tracer.extract(opentracing.HTTP_HEADERS, request.headers)
         span = tracer.start_span(
@@ -273,7 +273,7 @@ def follows_from(referenced_context=None):
 def start_child_span(parent_span, operation_name, tags=None, start_time=None):
     """A shorthand method that starts a child_of span for a given parent span.
 
-    Equivalent to calling
+    Equivalent to calling::
 
         parent_span.tracer().start_span(
             operation_name,
@@ -290,7 +290,7 @@ def start_child_span(parent_span, operation_name, tags=None, start_time=None):
     :param start_time: an explicit Span start time as a unix timestamp per
         time.time().
 
-    :return: Returns an already-started Span instance.
+    :return: an already-started Span instance.
     """
     return parent_span.tracer.start_span(
         operation_name=operation_name,