Better documentation - generate readthedocs compatible docs

[drolando]

@jstrfd Sorry, I've been very busy the last few days.

This is the in progress branch I had for adding better docs. It doesn't help you much yet as I haven't written many code samples yet, but I'll try to do it this evening or tomorrow

[jstrfd]

Any updates?

I am reading the comments in py_zipkin source code in zipkin.py, what is the difference between use case 1 and use case 2 in the zipkin span class?

"Usage #2: Trace a service call." VS "Usage #1: Start a trace with a given sampling rate."

[codefromthecrypt]

@drolando do you know the link for readthedocs off this branch?

[drolando]

Yeah sorry I didn't have time to finish this.

So the main point is that the first thing you need to do is to basically initialize the tracer and the transport. That's done by having a zipkin_span which sets a tranport_handler and either a sample_rate or custom zipkin_attrs.
You need to (and should) do this only once, ideally whenever a request arrives at your service or when your batch/script starts.

In all the other places you don't need to do this anymore and you just use zipkin_span(service_name='foo', span_name='bar').

This is kinda confusing which is why I'd like to separate out the tracer from zipkin_span entirely, but since it's a backward incompatible change I haven't done it just yet.

[drolando]

@adriancole I couldn't find a way to upload them to readthedocs without merging to master :(

So for now you either read the .rst files or checkout this branch, run make docs, cd docs/build and python -m SimpleHTTPServer 8888.

[jstrfd]

The version is 0.something....make all the things better and change the major version? Simpler is better.