Fix some v2.0.0 docs (#82)

* Lint doc line lengths.
* More formatting.
* Apply a similar formatting as the requests library.

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/ext/scope.py

@@ -31,16 +31,16 @@ def __init__(self, manager, span, finish_on_close):
         """Initialize a `Scope` for the given `Span` object.
 
         :param span: the `Span` wrapped by this `Scope`.
-        :param finish_on_close: whether span should automatically be
-            finished when `Scope#close()` is called.
+        :param finish_on_close: whether :class:`Span` should automatically be
+            finished when :meth:`Scope.close()` is called.
         """
         super(ThreadLocalScope, self).__init__(manager, span)
         self._finish_on_close = finish_on_close
         self._to_restore = manager.active
 
     def close(self):
-        """Mark the end of the active period for this {@link Scope},
-        updating ScopeManager#active in the process.
+        """Mark the end of the active period for this :class:`Scope`,
+        updating :attr:`ScopeManager.active` in the process.
         """
         if self.manager.active is not self:
             return

opentracing/propagation.py

@@ -23,9 +23,9 @@
 
 class UnsupportedFormatException(Exception):
     """UnsupportedFormatException should be used when the provided format
-    value is unknown or disallowed by the Tracer.
+    value is unknown or disallowed by the :class:`Tracer`.
 
-    See Tracer.inject() and Tracer.extract().
+    See :meth:`Tracer.inject()` and :meth:`Tracer.extract()`.
     """
     pass
 
@@ -34,25 +34,25 @@ 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
 
 
 class SpanContextCorruptedException(Exception):
-    """SpanContextCorruptedException should be used when the underlying span
-    context state is seemingly present but not well-formed.
+    """SpanContextCorruptedException should be used when the underlying
+    :class:`SpanContext` 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,38 +62,38 @@ 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'
     """
-    The TEXT_MAP format represents SpanContexts in a python dict mapping from
-    strings to strings.
+    The TEXT_MAP format represents :class:`SpanContext`\ s in a python ``dict``
+    mapping from strings to strings.
 
     Both the keys and the values have unrestricted character sets (unlike the
     HTTP_HEADERS format).
 
-    NOTE: The TEXT_MAP carrier dict may contain unrelated data (e.g.,
-    arbitrary gRPC metadata). As such, the Tracer implementation should use a
-    prefix or other convention to distinguish Tracer-specific key:value
-    pairs.
+    NOTE: The TEXT_MAP carrier ``dict`` may contain unrelated data (e.g.,
+    arbitrary gRPC metadata). As such, the :class:`Tracer` implementation
+    should use a prefix or other convention to distinguish tracer-specific
+    key:value pairs.
     """
 
     HTTP_HEADERS = 'http_headers'
     """
-    The HTTP_HEADERS format represents SpanContexts in a python dict mapping
-    from character-restricted strings to strings.
+    The HTTP_HEADERS format represents :class:`SpanContext`\ s in a python
+    ``dict`` mapping from character-restricted strings to strings.
 
     Keys and values in the HTTP_HEADERS carrier must be suitable for use as
     HTTP headers (without modification or further escaping). That is, the
     keys have a greatly restricted character set, casing for the keys may not
     be preserved by various intermediaries, and the values should be
     URL-escaped.
 
-    NOTE: The HTTP_HEADERS carrier dict may contain unrelated data (e.g.,
-    arbitrary gRPC metadata). As such, the Tracer implementation should use a
-    prefix or other convention to distinguish Tracer-specific key:value
-    pairs.
+    NOTE: The HTTP_HEADERS carrier ``dict`` may contain unrelated data (e.g.,
+    arbitrary gRPC metadata). As such, the :class:`Tracer` implementation
+    should use a prefix or other convention to distinguish tracer-specific
+    key:value pairs.
     """

opentracing/scope.py

@@ -22,38 +22,46 @@
 
 
 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.
+    """A scope formalizes the activation and deactivation of a :class:`Span`,
+    usually from a CPU standpoint. Many times a :class:`Span` will be extant
+    (in that :meth:`Span.finish()` has not been called) despite being in a
+    non-runnable state from a CPU/scheduler standpoint. For instance, a
+    :class:`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 :class:`Span` is scheduled and on the path.
+
+    :param manager: the :class:`ScopeManager` that created this :class:`Scope`.
+    :type manager: ScopeManager
+
+    :param span: the :class:`Span` used for this :class:`Scope`.
+    :type span: Span
     """
     def __init__(self, manager, span):
-        """Initializes a `Scope` for the given `Span` object.
-
-        :param manager: the `ScopeManager` that created this `Scope`
-        :param span: the `Span` used for this `Scope`
-        """
+        """Initializes a scope for *span*."""
         self._manager = manager
         self._span = span
 
     @property
     def span(self):
-        """Returns the `Span` wrapped by this `Scope`."""
+        """Returns the :class:`Span` wrapped by this :class:`Scope`.
+
+        :rtype: Span
+        """
         return self._span
 
     @property
     def manager(self):
-        """Returns the `ScopeManager` that created this `Scope`."""
+        """Returns the :class:`ScopeManager` that created this :class:`Scope`.
+
+        :rtype: ScopeManager
+        """
         return self._manager
 
     def close(self):
-        """Marks the end of the active period for this `Scope`,
-        updating `ScopeManager#active` in the process.
+        """Marks the end of the active period for this :class:`Scope`, updating
+        :attr:`ScopeManager.active` in the process.
 
-        NOTE: Calling `close()` more than once on a single `Scope` instance
+        NOTE: Calling this method more than once on a single :class:`Scope`
         leads to undefined behavior.
         """
         pass
@@ -63,7 +71,7 @@ def __enter__(self):
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
-        """Calls `close()` when the execution is outside the Python
+        """Calls :meth:`close()` when the execution is outside the Python
         Context Manager.
         """
         self.close()

opentracing/scope_manager.py

@@ -25,9 +25,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`).
+    """The :class:`ScopeManager` interface abstracts both the activation of
+    a :class:`Span` and access to an active :class:`Span`/:class:`Scope`.
     """
     def __init__(self):
         # TODO: `tracer` should not be None, but we don't have a reference;
@@ -37,27 +36,30 @@ def __init__(self):
         self._noop_scope = Scope(self, self._noop_span)
 
     def activate(self, span, finish_on_close):
-        """Makes a `Span` instance active.
+        """Makes a :class:`Span` active.
 
-        :param span: the `Span` that should become active.
-        :param finish_on_close: whether span should be automatically
-            finished when `Scope#close()` is called.
+        :param span: the :class:`Span` that should become active.
+        :param finish_on_close: whether :class:`Span` should be automatically
+            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.
+        :rtype: Scope
+        :return: a :class:`Scope` to control the end of the active period for
+            *span*. It is a programming error to neglect to call
+            :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`.
+        """Returns the currently active :class:`Scope` which can be used to access the
+        currently active :attr:`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.
+        If there is a non-null :class:`Scope`, its wrapped :class:`Span`
+        becomes an implicit parent of any newly-created :class:`Span` at
+        :meth:`Tracer.start_active_span()` time.
 
-        :return: the `Scope` that is active, or `None` if not available.
+        :rtype: Scope
+        :return: the :class:`Scope` that is active, or ``None`` if not
+            available.
         """
         return self._noop_scope