[docs] Refactor documentation (#539)

* [docs] update README

- add badges
- add references to external documentation
- reword a few things
- remove information about versioning

* [docs] fix badge formatting

* [docs] separate docs into logical partitions

* [docs] fix links, typos, consistency

* [docs] a few more small fixes

* [docs] address nits

* [docs] fix HTTPPropagator usage docs (#546)

* [docs/django] add Django tracer logging configuration docs

* [docs] address nits
- use only pypi version badge, drop release version
- revert mysql naming changes
- remove makefile link command
- add missing supported distributed tracing libraries
- dynamic copyright date
- misc. wording fixes

* [docs] refactor pre-sampling (to client sampling)

* [docs] move aiohttp to web integrations

* [docs] add web framework preamble

* [docs] remove empty file

Author: Kyle-Verhoog

README.md

@@ -0,0 +1,90 @@
+# dd-trace-py
+
+[![CircleCI](https://circleci.com/gh/DataDog/dd-trace-py/tree/master.svg?style=svg)](https://circleci.com/gh/DataDog/dd-trace-py/tree/master)
+[![Pyversions](https://img.shields.io/pypi/pyversions/ddtrace.svg?style=flat)](https://pypi.org/project/ddtrace/)
+[![PypiVersions](https://img.shields.io/pypi/v/ddtrace.svg)](https://pypi.org/project/ddtrace/)
+
+`ddtrace` is Datadog's tracing library for Python.  It is used to trace requests
+as they flow across web servers, databases and microservices so that developers
+have great visiblity into bottlenecks and troublesome requests.
+
+## Getting Started
+
+For a basic product overview, installation and quick start, check out our
+[setup documentation][setup docs].
+
+For more advanced usage and configuration, check out our [API
+documentation][pypi docs].
+
+For descriptions of terminology used in APM, take a look at the [official
+documentation][visualization docs].
+
+[setup docs]: https://docs.datadoghq.com/tracing/setup/python/
+[pypi docs]: http://pypi.datadoghq.com/trace/docs/
+[visualization docs]: https://docs.datadoghq.com/tracing/visualization/
+
+
+## Development
+
+
+### Testing
+
+
+#### Environment
+
+The test suite requires many backing services such as PostgreSQL, MySQL, Redis
+and more. We use ``docker`` and ``docker-compose`` to run the services in our CI
+and for development. To run the test matrix, please [install docker][docker] and
+[docker-compose][docker-compose] using the instructions provided by your platform. Then
+launch them through:
+
+    $ docker-compose up -d
+
+
+[docker]: https://www.docker.com/products/docker
+[docker-compose]: https://www.docker.com/products/docker-compose
+
+
+#### Running the Tests
+
+Once docker is up and running you should be able to run the tests. To launch a
+single test manually. For example to run the tests for `redis-py` 2.10 on Python
+3.5 and 3.6:
+
+    $ tox -e '{py35,py36}-redis{210}'
+
+To see the defined test commands see `tox.ini`.
+
+To launch the complete test matrix run:
+
+    $ tox
+
+
+### Continuous Integration
+
+We use CircleCI 2.0 for our continuous integration.
+
+
+#### Configuration
+
+The CI tests are configured through [config.yml](.circleci/config.yml).
+
+
+#### Running Locally
+
+The CI tests can be run locally using the `circleci` CLI. More information about
+the CLI can be found at https://circleci.com/docs/2.0/local-jobs/.
+
+After installing the `circleci` CLI, you can run jobs by name. For example:
+
+    $ circleci build --job django
+
+
+### Benchmarking
+
+When two or more approaches must be compared, please write a benchmark in the
+[benchmark.py](tests/benchmark.py) module so that we can measure the efficiency
+of the algorithm. To run your benchmark, just:
+
+    $ python -m tests.benchmark
+

README.rst

@@ -1,5 +1,5 @@
 """
-Instrument `aiopg` to report a span for each executed Postgres queries::
+Instrument aiopg to report a span for each executed Postgres queries::
 
     from ddtrace import Pin, patch
     import aiopg

ddtrace/contrib/aiopg/__init__.py

@@ -28,6 +28,19 @@
     tracer.trace("something")
     # your code ...
 
+To have Django capture the tracer logs, ensure the ``LOGGING`` variable in
+``settings.py`` looks similar to::
+
+    LOGGING = {
+        'loggers': {
+            'ddtrace': {
+                'handlers': ['console'],
+                'level': 'WARNING',
+            },
+        },
+    }
+
+
 The available settings are:
 
 * ``DEFAULT_SERVICE`` (default: ``'django'``): set the service name used by the

ddtrace/contrib/django/__init__.py

@@ -17,7 +17,6 @@
     # Use a pin to specify metadata related to this connection
     Pin.override(conn, service='mysql-users')
 
-This package works for mysql.connector version 2.1.x.
 Only the default full-Python integration works. The binary C connector,
 provided by _mysql_connector, is not supported yet.
 

ddtrace/contrib/mysql/__init__.py

@@ -17,9 +17,9 @@
     # Use a pin to specify metadata related to this connection
     Pin.override(conn, service='mysql-users')
 
-This package works for mysqlclient or MySQL-python
-Only the default full-Python integration works. The binary C connector,
-provided by _mysql, is not supported yet.
+This package works for mysqlclient or MySQL-python. Only the default
+full-Python integration works. The binary C connector provided by
+_mysql is not yet supported.
 
 Help on mysqlclient can be found on:
 https://mysqlclient.readthedocs.io/

ddtrace/contrib/mysqldb/__init__.py

@@ -1,4 +1,4 @@
-"""Instrumeent pymysql to report MySQL queries.
+"""Instrument pymysql to report MySQL queries.
 
 ``patch_all`` will automatically patch your pymysql connection to make it work.
 ::

ddtrace/contrib/pymysql/__init__.py

@@ -40,7 +40,8 @@ def inject(self, span_context, headers):
             def parent_call():
                 with tracer.trace("parent_span") as span:
                     headers = {}
-                    HTTPPropagator.inject(span.context, headers)
+                    propagator = HTTPPropagator()
+                    propagator.inject(span.context, headers)
                     url = "<some RPC endpoint>"
                     r = requests.get(url, headers=headers)
 
@@ -92,7 +93,8 @@ def extract(self, headers):
             from ddtrace.propagation.http import HTTPPropagator
 
             def my_controller(url, headers):
-                context = HTTPPropagator.extract(headers)
+                propagator = HTTPPropagator()
+                context = propagator.extract(headers)
                 tracer.context_provider.activate(context)
 
                 with tracer.trace("my_controller") as span:

ddtrace/propagation/http.py

@@ -0,0 +1,9 @@
+{{ toctree(includehidden=theme_sidebar_includehidden, collapse=theme_sidebar_collapse) }}
+{% if theme_extra_nav_links %}
+<hr />
+<ul>
+    {% for text, uri in theme_extra_nav_links.items() %}
+    <li class="toctree-l1"><a href="{{ uri }}">{{ text }}</a></li>
+    {% endfor %}
+</ul>
+{% endif %}