Hi James, On Tue, Nov 16, 2010 at 3:06 PM, James Henstridge <[email protected]> wrote: > On Sun, Nov 14, 2010 at 11:12 AM, Jamu Kakar <[email protected]> wrote: >> On Sun, Nov 14, 2010 at 2:14 PM, James Henstridge <[email protected]> wrote: >>> On Wed, Nov 10, 2010 at 11:33 PM, Jamu Kakar <[email protected]> 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. -- storm mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/storm
