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 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. -- storm mailing list [email protected] Modify settings or unsubscribe at: https://lists.ubuntu.com/mailman/listinfo/storm
