Am 12.09.2007 um 16:01 schrieb Alec Thomas: > On 9/12/07, Christopher Lenz <[EMAIL PROTECTED]> wrote: >> 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? > > None at all, +1. > > While we're discussing docs, perhaps we should revisit an earlier > discussion about fixing the user documentation. We proposed doing > exactly what you've done for Genshi: keeping the canonical > documentation > in svn as restructured text, and exposing it through includes. This > of course solves the current problem Trac has of documenting multiple > versions. > > Thoughts?
I think that improving the documentation situation is very important, and should be a core focus for 0.12. We can't just copy the Genshi way here, though, because the docs will still need to be accessible by users over the web. So the idea here would be to add a "help" subsystem, where plugins store reST files in their package data, and there's a component that will render them online, build a TOC, make them searchable, etc. This would also get rid of all the default pages "polluting" every new Trac environment. Related to that is separating the administration docs from the user docs. The admin stuff can basically be provided as generated docs (similar to the Genshi docs), and mirrored on the Trac site (as in trac.edgewall.org) for convenience. Unlike the user documentation, it does not need be accessible to users through every Trac deployment. That's just a very quick outline of my current ideas in that direction, we'll definitely need to work out the (many) details. 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 -~----------~----~----~----~------~----~------~--~---
