[storm] get_select_expr

[Jamu Kakar]

Hi James,

On Tue, Nov 16, 2010 at 3:06 PM, James Henstridge <james at jamesh.id.au> wrote:
> On Sun, Nov 14, 2010 at 11:12 AM, Jamu Kakar <jkakar at kakar.ca> wrote:
>> On Sun, Nov 14, 2010 at 2:14 PM, James Henstridge <james at jamesh.id.au> wrote:
>>> On Wed, Nov 10, 2010 at 11:33 PM, Jamu Kakar <jkakar at kakar.ca> wrote:
>>>> We already have API documentation generated from the source:
>>>>
>>>> http://people.canonical.com/~jkakar/storm/
>>>>
>>>> We can reference the API from the manual, but I don't think we need to
>>>> reproduce it there.
>>>
>>> I think it would be useful to include reference documentation in the
>>> manual.  If we converted our docstrings to reStructuredText, it would
>>> be pretty easy to automatically extract them for Sphinx based
>>> documentation.
>>>
>>> The only possible downside to this is if it causes problems for the
>>> pydoctor API docs you've generated.
>>
>> According to this:
>>
>> https://dev.launchpad.net/PythonStyleGuide#Docstrings
>>
>> Docstrings that are valid ReST will be handled by Pydoctor, but it
>> looks like we'd need to keep fields in Epydoc format (which they are
>> now).  It looks like there an extension for Sphinx to make it work
>> with Epydoc:
>>
>> http://git.savannah.gnu.org/cgit/kenozooid.git/tree/doc/extapi.py
>
> My personal preference would be to have the reference docs in the
> manual, rather than just linking to pydoctor documentation.
>
>> I haven't tried it, but it's probably worth exploring.  On the other
>> hand, if Sphinx's API documentation is good enough we can stop using
>> Pydoctor and go with pure ReST docstrings.
>
> The docstring extraction seems to work pretty well.  You can include
> the extracted documentation for a method with a directive like this:
>
> .. automethod:: ResultSet.set
>
> And it will insert the docstring along with the method signature.
> There is also a coverage checker extension for sphinx, so it would be
> pretty easy to check whether we'd missed any methods.

+1, this all sounds good to me.  Let's do it! :)

Thanks,
J.