I've been mostly lurking, but would like to offer a few comments... reST to HTML is very straightforward, the docutils pacage has an rst2Html script to do exactly that (and it is just a few lines of code). Sphinx, as Yarko has pointed out, is a tool chain using reST that adds better facilities for large, multi-section documents in reST.
I think reST (and Sphinx) would be a great choice for documentation. Sphinx is pretty new, but I have used reST for a lot of in-house doc and it is a very useable and maintainable markup language. As for combining a wiki with reST, moinmoin and Trac have done this: http://moinmoin.wikiwikiweb.de/HelpOnParsers/ReStructuredText http://bitten.edgewall.org/wiki/WikiRestructuredText so it would certainly be possible to integrate with a web2py-based wiki. The only think I would say to keep in mind is this: wikis and structured (not reStructured) documentation are quite different in intent, workflow & delivery, and although you can make the argument that wiki pages would just become sections of the documentation the reality is that this would take effort to keep the wiki itself quite structured (not their natural state). I'm in favor of a wiki with reST as its markup language. And I am in favor of using reST/Sphinx for documentation. I'm not convinced (based on having done several doc & wiki projects) that combining the two is ideal. I think if you treat the documentation as a built deliverable with reST source files, and handle contributions, revisions, etc through source control. This makes it dead-simple to couple doc revisions with the web2py source itself, something that is otherwise complicated if you try to build doc with a live-wiki. I've not gone through every one, but I think you'd find most if not all of the projects in http://sphinx.pocoo.org/examples.html take this approach. Having a wiki is still good.... it's great for code recipes and quick doc on new features, news, areas that are rapidly changing, etc. But I think having a dedicated set of sources for the documentation would result in a better organized, more coherent set of final docs. And the wiki can stil have links to HTML pages generated from the doc source. I have yet to really see a project with wiki-based documentation that did not seem somewhat scattered. chris --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "web2py Web Framework" group. To post to this group, send email to web2py@googlegroups.com To unsubscribe from this group, send email to web2py+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/web2py?hl=en -~----------~----~----~----~------~----~------~--~---
