You've made some very good points. Would the following make sense?
Use the wiki for the initial gathering of doc pages, then after the first sphinx-based documentation is produced, just clean the wiki of those pages. After that, just use the wiki for contributed recipes and other pages, some of which are selectively migrated to sphinx. Keep the changes due to new releases in sphinx only. Just asking. --greg-- On Feb 27, 6:53 am, chris p <chrispri...@gmail.com> wrote: > 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 > inhttp://sphinx.pocoo.org/examples.htmltake 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 -~----------~----~----~----~------~----~------~--~---
