Hey all, we've not really established a standard for how docstrings are formatted in Trac (AFAIK). In the interest of being to be able to provide generated API documentation in the future, but also for general consistency, I think we really need to do that.
I suggest we adopt reStructuredText. If there's anything that comes somewhat close to a standard for Python docstrings, that's arguably the one. I've been using reST (combined with epydoc 3.0beta1) for the Genshi and Babel docs with great success. Please download a recent source release of either of those projects, and open the doc/api/index.html file in your favorite browser. I think that at some point in the future we should be doing the same for Trac, considering how the APIs are becoming more and more important due to steadily increasing plugin development. Now, while most of the docstrings in Trac are pretty much plain text, there are many that use Wiki formatting, or even the old epydoc format (mea culpa on that one). I'm not suggesting we go back and change them all, that can be done slowly and incrementally. But for new docstrings we should use reST. Objections? Cheers, Chris -- Christopher Lenz cmlenz at gmx.de http://www.cmlenz.net/ --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "Trac Development" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [EMAIL PROTECTED] For more options, visit this group at http://groups.google.com/group/trac-dev?hl=en -~----------~----~----~----~------~----~------~--~---
