[django] improve docs

Author: Emanuele Palazzetti

ddtrace/contrib/django/__init__.py

@@ -1,19 +1,52 @@
 """
-The Django middleware will trace requests, database calls and template
+The Django integration will trace requests, database calls and template
 renders.
 
 To install the Django tracing middleware, add it to the list of your
-application's installed in middleware in settings.py::
+installed apps and in your middleware classes in ``settings.py``::
 
+    INSTALLED_APPS = [
+        # ...
+
+        # the order is not important
+        'ddtrace.contrib.django',
+    ]
 
     MIDDLEWARE_CLASSES = (
-        ...
+        # the tracer must be the first middleware
         'ddtrace.contrib.django.TraceMiddleware',
         ...
     )
 
-    DATADOG_SERVICE = 'my-app'
+The configuration of this integration is all namespaced inside a single
+Django setting, named ``DATADOG_APM``. For example, your ``settings.py``
+may contain::
+
+    DATADOG_APM = {
+        'DEFAULT_SERVICE': 'my-django-app',
+    }
+
+If you need to access to the tracing settings, you should::
+
+    from ddtrace.contrib.django.conf import settings as dd_settings
+
+    tracer = dd_settings.DEFAULT_TRACER
+    tracer.trace("something")
+    # your code ...
+
+The available settings are:
 
+* ``DEFAULT_TRACER`` (default ``ddtrace.tracer``): set the default tracer
+  instance that is used to trace Django internals. By default the ``ddtrace``
+  tracer is used.
+* ``DEFAULT_SERVICE`` (default: ``django``): set the service name used by the
+  tracer. Usually this configuration must be updated with a meaningful name.
+* ``ENABLED``: (default: ``not django_settings.DEBUG``): set if the tracer
+  is enabled or not. When a tracer is disabled, Django internals are not
+  automatically instrumented and the requests are not traced even if the
+  ``TraceMiddleware`` is properly installed. This settings cannot be changed
+  at runtime and a restart is required. By default the tracer is disabled
+  when in ``DEBUG`` mode, enabled otherwise.
 """
 from ..util import require_modules
 

ddtrace/contrib/django/conf.py

@@ -61,7 +61,9 @@ class DatadogSettings(object):
     A settings object, that allows Datadog settings to be accessed as properties.
     For example:
 
-        # TODO
+        from ddtrace.contrib.django.conf import settings
+
+        tracer = settings.DEFAULT_TRACER
 
     Any setting with string import paths will be automatically resolved
     and return the class, rather than the string literal.