Merge pull request #78 from DataDog/awang/doc_cleanup

clarify python docs based on user tests

Author: awang

ddtrace/contrib/flask/__init__.py

@@ -1,17 +1,26 @@
 """
-The flask trace middleware will track request timings and templates. It
+The Flask trace middleware will track request timings and templates. It
 requires the `Blinker <https://pythonhosted.org/blinker/>`_ library, which
 Flask uses for signalling.
 
-To install the middleware, do the following::
+To install the middleware, add::
+
+    from ddtrace import tracer
+    from ddtrace.contrib.flask import TraceMiddleware
+
+and create a `TraceMiddleware` object::
+
+    traced_app = TraceMiddleware(app, tracer, service="my-flask-app")
+
+Here is the end result, in a sample app::
 
     from flask import Flask
     import blinker as _
 
     from ddtrace import tracer
     from ddtrace.contrib.flask import TraceMiddleware
 
-    app = Flask(...)
+    app = Flask(__name__)
 
     traced_app = TraceMiddleware(app, tracer, service="my-flask-app")
 

ddtrace/contrib/flask_cache/__init__.py

@@ -2,7 +2,16 @@
 The flask cache tracer will track any access to a cache backend.
 You can use this tracer together with the Flask tracer middleware.
 
-To install the tracer, do the following::
+To install the tracer, ``from ddtrace`` needs to be added::
+
+    from ddtrace import tracer
+    from ddtrace.contrib.flask_cache import get_traced_cache
+
+and the tracer needs to be initialized::
+
+    Cache = get_traced_cache(tracer, service='my-flask-cache-app')
+
+Here is the end result, in a sample app::
 
     from flask import Flask
 

docs/index.rst

@@ -18,9 +18,11 @@ Install with :code:`pip` but point to Datadog's package repo::
 
     $ pip install ddtrace --find-links=https://s3.amazonaws.com/pypi.datadoghq.com/trace/index.html
 
-If you are using a supported integration, proceed to the :ref:`relevant instructions <integrations>` next.
+Quick Start (Auto Instrumentation)
+-----------
+If you are using a supported integration, proceed to the :ref:`relevant instructions<integrations>` for the integrations you are interested in.
 
-Quick Start
+Quick Start (Manual Instrumentation)
 -----------
 
 Adding tracing to your code is very simple. As an example, let's imagine we are adding
@@ -33,10 +35,8 @@ tracing from scratch to a small web app::
     @route("/home")
     def home(request):
 
-        with tracer.trace('web.request') as span:
+        with tracer.trace('web.request', service=service, resource='home') as span:
             # set some span metadata
-            span.service = service
-            span.resource = "home"
             span.set_tag('web.user', request.username)
 
             # trace a database request