spotify/luigi — pull request #272 by jcrobak (2014-02-08 16:17:36+00:00)
Title: Sphinx docs

Since actions speak louder than words on the ML, here's an example of implementing sphinx documentation. I've broken this PR into logical commits -- the initial sphinx setup, docstring updates to luigi.task, docstring updates to luigi.parameter, and some sphinx config/page updates to pull in the docs for luigi.task and luigi.parameter. I thought I'd share this before investing more time to get feedback on the direction.

I've uploaded the html that it generates here: http://jcrobak-sandbox.s3.amazonaws.com/luigi-sphinx/index.html (notably checkout the api docs for luigi.task and luigi.parameter: http://jcrobak-sandbox.s3.amazonaws.com/luigi-sphinx/api.html )

Happy to field comments on the docs I supplied as well as the sphinx implementation, etc.

One thing that became pretty apparently during this exercise is that the implementation is too tightly coupled with the Task and Parameter interfaces that users are expected to implement. I could do a more finer-grained documentation of "user facing" apis, but arguably this should be fixed in the implementation, too. (To get an idea of what I mean, see all the methods/args of `luigi.Task` that are public, e.g. `get_params`, `get_global_params`, `get_param_value`, `initialized`, `from_input`, `deps`, etc that are not something that are for the framework and not expected to be used in user space).