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