documentation

[BurntSushi]

So I would like to write documentation for Wapiti (in particular, before attacking #22). I think it will help me understand the internals better and will have the added benefit of making it easier for others to contribute.

As I see it, there are actually three pieces of Wapiti that call out for documentation:

1. Regular ol' public API documentation. You've already done some fair amount of work in filling in docstrings, but it has to get into some consumable format. Most are using Sphinx these days, but I might like to try using my pdoc library to automatically generate documentation.
2. Documentation for how to create new operations. This should be a specification of the DSL.
3. The DSL internals. I think the metaclasses require careful attention, because they make it very difficult to reason locally about any bit of code. (In my experience.)

[mahmoud]

pdoc looks pretty perfect for this sort of thing. I'm a big fan of docstrings and not a big fan of many of Sphinx's hassles. Documentation on creating new Operations would be amazing, too. As for the Wapiti internals, those are a bit in flux, so I think you've got the right order right there.

Specifically, a lot of QueryOperation specific stuff got mixed into Operation and vice-versa. Another thing I've been doing on the hematite_integration branch is trying to remedy that and make a clearer set of steps/hooks in processing Operations.

Looking forward to some pdocs!