Rewrite

[mrgaaron]

Proposed re-write of Python client for 1.0 version

[blakesmith]

Can you please briefly describe the strategy you're using for documentation? I see sphinx mentioned in the Makefile and lots of doctree files, but am not familiar with them, nor are they anywhere else in our stack.

[blakesmith]

Also, it looks like the generated html from documentation is checked in. Is this the desired behavior?

[blakesmith]

Can you provide a high level overview of your changes? I'm not familiar with the scope of this rewrite, and it'd be nice to have a little context as to what the desired goals of this rewrite are.

[mrgaaron]

Blake -

Putting in the the built doc files was unintentional. I pushed up a version with those removed and will have reopen the pull request.

I'll summarize the goals in the new request. But as for the documentation system, the best place to start is here: http://sphinx-doc.org/. Sphinx is essentially Python's equivalent of javadoc, with the documentation written in a format called restructured text that has some similarities to markdown. I chose to go the route where the docs are built automatically from docstrings in the Python code. The eventual plan is to host the HTML form of the docs in github similarly to how we host the javadoc.

[mrgaaron]

Oops, I guess closing and reopening was unnecessary. Github is smarter than I thought.

Anyway, the rationale behind the rewrite:

1. Start pushing the client API implementations towards the future of the REST API - i.e. deprecating access to series ID, deprecating increment, implementing single value
2. Implementation of cursoring for series and data reads
3. Clean up the architecture of the API (make things more Pythonic) and improve test coverage

[blakesmith]

This has been pushed to a 1.0 branch here: https://github.com/tempodb/tempodb-python/tree/1.0 where further testing can be done.