[storm] get_select_expr

[Jamu Kakar]

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

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.

Thanks,
J.