On Wed, Jul 1, 2009 at 1:55 AM, Roberto Nobrega<rwnobr...@gmail.com> wrote: > > The following was raised after SymPy documentation day. > > > Currently we have 3 main sources of documentation: > > - GoogleCode Wiki. > - MediaWiki (wiki.sympy.org). > - Sphinx (docs.sympy.org). > > The current state is very messy. In my opinion, there must be no > repeated information, and we should define what goes where. (Related > issue: http://code.google.com/p/sympy/issues/detail?id=707) > > > Sphinx has the following advantages, pointed by Ondrej: > > <ondrek> the .rst is nice, that we ship it in the release tarball > <ondrej> and it imho looks better than the wiki > <ondrej> plus we can use autodoc feature of sphinx, that extracts > docstrings from inside sympy > <ondrej> plus once we fix it, a pdf documentation will be possible to > > MediaWiki and GoogleCode Wiki are far more accessible to newcomers and > changes are committed instantaneously. > > > Just for example, I see no reason for this to be on Sphinx: > > http://docs.sympy.org/outreach.html#google-summer-of-code > > Also, there is GSoC info on GoogleCode Wiki and MediaWiki as well: > > http://wiki.sympy.org/wiki/GSoC2009Application > http://code.google.com/p/sympy/wiki/GSoC2009 > > > As we discussed on IRC, I propose: > > - GoogleCode: Burn it. Except for FrontPage, Downloads, etc. > > - Sphinx: Only for Tutorial, User Guide and Modules Reference. > > - MediaWiki: Everything else. Including: Patches tutorial, GSoC info, > Development tips, Bibliographical references, Quick examples / > cookbooks, Future plans, Project reports. > > > So, I propose the following actions: > > - Move (and then delete) all wikis from GoogleCode to MediaWiki. I > started some work on this. > > - Delete from MediaWiki repeated stuff already on Sphinx and vice-versa. > > > Some remarks: > > - We must be sure no information will be lost on this process. > > - We need some way to tell people our choices (e.g., not to use > GoogleCode Wiki). > > - There is a very annoying Unicode bug in MediaWiki that must be fixed > if we opt for using it. > > > Is that subject too much preciosity of my part? What do you people > think? Ondrej, for example, is against moving Patches tutorial from > Sphinx to MediaWiki. Let's try to reach a consensus.
I suggest to use sphinx for everything, except some things that change a lot, that should be on the wiki. I think tutorials are good to be in the .rst forms, because the examples should be doctested. Otherwise I agree. There is one more problem, that mediawiki is nontrivial to manage (you need to maintain mysql, users, images, lighttpd, and the php files for mediawiki). It took me about 3 or 4 hours to move it from one server to another, due to lots of small silly problems. The google code wiki is less versatile, and sometimes down or read only, but I don't have to maintain it. I'll try to learn how to maintain things so that I can move it across servers easily. If anyone has any advice, I am interested. Ondrej --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "sympy" group. To post to this group, send email to sympy@googlegroups.com To unsubscribe from this group, send email to sympy+unsubscr...@googlegroups.com For more options, visit this group at http://groups.google.com/group/sympy?hl=en -~----------~----~----~----~------~----~------~--~---
