[storm] get_select_expr

[James Henstridge]

On Sun, Nov 14, 2010 at 11:12 AM, Jamu Kakar <jkakar at kakar.ca> wrote:
> Hi James,
>
> 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:
>>> Hi,
>>>
>>> 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.

James.