I do like the idea of the Sphinx site as well. - it looks great and is easy to setup. - It is not hard to update, just check out the source and update the reST source.
After reading what Yarko said, in my mind, the only missing feature Sphinx would be user-contributed comments. - The reason I say that is that http://www.php.net/docs is one of the most useful documentation sites I have every seen. I know just where to find everything I need there. It's too bad we don't have something like that we can use for web2py. - In my mind that site has 3 main advantages. 1. All of the documentation is there in one place. 2. It is well organized in a tree/folder structure like Sphinx. 3. It has user-contributed comments. This is crucial in my mind because many times when coding in PHP (at work) I find what I need to know in the comments. And it stays organized because the comments are all having to do with the official documentation listed above them (or other comments). Just more ideas. Paul On Fri, Feb 27, 2009 at 11:09 PM, Yarko Tymciurak <yark...@gmail.com> wrote: > On Fri, Feb 27, 2009 at 6:48 PM, mdipierro <mdipie...@cs.depaul.edu>wrote: > >> >> I do not like the idea of things moving out of the wiki and never >> coming back. Things will always need small updates and that it >> critical. > > > Small updates can happen in Wiki; when stable, they can happen in Sphinx I > think this is no problem - sphinx can always be updated; it just will not be > the same way as a wiki. > > >> >> We can start with that but then we need to build a web interface >> directly to the sphinx docs. > > > This will be some challenge, since sphinx builds indexes and cross > references on entire doc... you will be rebuilding all indexes with any > edit? > > Aside from the technical challenges, this then will not be documentation in > the form of a book, which stabilizes, gets reviewed, etc. > > I think if you want a wiki for everybody to easily contribute their > learnings, then a wiki is fine. > > If you want dependable, readable, consistent documentation, like many, many > other projects do - Python not the least of them, then what is the basis of > what you "do not like"? > > In any case, I am not for this. There are > some interesting possibilities to live sphinx, but even then, the concept of > submitted vs. reviewed vs. published changes is (in my mind) important, and > differentiates this in a fundamental and important way from a wiki. > > A wiki is useful and important; it is also quite different than a > document. > > I am not interested in participating in degenerating a form - whose aim is > to generate a reliable, consistent, readable document - into a printed > version of a wiki, although you can do that (I just am not interested). > > People like your book because you _owned_ the contents, even with the > contributions of others, and that meant a consistency which made it > readable, consistent and therefore useful. > > If you want a wiki, then you don't need sphinx - google searches over wiki > pages will suffice. > > I am interested in the document concept, and think a wiki is a good ground > for tilling the material which stabilizes into something worthy of being > part of a coherent form (not to diminish by any means the utility of what is > in a wiki - it just is a different form, and a different result - it is also > more accesible to contributors, and that is good). > > We have had this discussion enough times. Wiki away. I will contribute > to the wiki too at times. > > Let me know if you're interested in the process of creating a community > written book; in that I would be more interested. > > Regards, > Yarko > >> >> >> Massimo >> >> On Feb 27, 6:36 pm, Yarko Tymciurak <yark...@gmail.com> wrote: >> > On Fri, Feb 27, 2009 at 1:31 PM, Paul Eden <benchl...@gmail.com> wrote: >> > > +1 I like these ideas. >> > >> > > One thing I would add. >> > >> > > If we do have a wiki and sphinx in source control then we should have >> one >> > > place where users can search through *both* places. >> > >> > > That way they don't have to look through one and then look through the >> > > other to find answers. >> > >> > Well - by nature, this would be a diode -> that is, a one way door: >> > >> > So I can imagine how the wiki, when a page / topic gets mature and >> migrates >> > to the sphinx will point to that. But the sphinx will not point back >> (in >> > the case the wiki has new, not yet in sphinx updates). >> > >> > Which raises an interesting point: >> > >> > Maintenance of sphinx sources should be concerned with evlolving, >> > improving, and doing "book like" changes (cross references). New ideas >> or >> > more than slow evolutions / additions should still happen in the wiki. >> > >> > I see the wiki as being public enough and encouraging input from broader >> > population, so it _should_ go through the chaos->settling steps for a >> given >> > topic; the sphinx place should be like the cask - the place where what >> > happens is mostly mellowing (or polishing / nice diagrams, so forth). >> > >> > Having said that - Massimo called for a general organization of the Wiki >> > into gross topic areas (as I understood). >> > >> > If we agree on that, then the sphinx sources can easily reference the >> areas >> > from which they came; the wiki then should make it easy to spot any new >> > things... >> > >> > Would this satisfy your request, or did you have something more in mind? >> > >> > Yarko >> > >> > >> > >> > > Paul >> > >> > > On Fri, Feb 27, 2009 at 11:06 AM, Yarko Tymciurak <yark...@gmail.com >> >wrote: >> > >> > >> I haven't fully thought about this yet, but in general - >> > >> Wiki == freeform idea collection; I agree that some structure to >> begin >> > >> and guide is good; >> > >> > >> Good place for transient information; >> > >> > >> I would think once content is in a sphinx doc (and I agree completely >> w/ >> > >> source control - much like what the Python 3 Patterns book is >> following) it >> > >> should be pulled form the wiki (maybe a final revision referring to >> the >> > >> "published" page, and then new updates maintained in sphinx doc). >> > >> > >> This will prevent the considerable problem of diverging documentation >> ("I >> > >> documented it here; Oh! Look - there's something similar, but a >> little >> > >> different here - which is right? which is current?") >> > >> > >> Perhaps a feedback look from sphinx would be useful (we organized >> best w/ >> > >> these sections, so we now re-organize the wiki to - at least at a >> high level >> > >> - match). >> > >> > >> Anyway, I have an idea, I don't know where to put it, I want to >> share it >> > >> --- this is definitely wiki space, and others can add / update.... >> > >> > >> Just rambling thoughts during lunch... >> > >> > >> Yarko >> > >> > >> On Fri, Feb 27, 2009 at 9:27 AM, cjparsons <cjparso...@yahoo.co.uk >> >wrote: >> > >> > >>> > 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. >> > >>> +1. Once the accepted documentation is there I think we need to keep >> > >>> the wiki to recipies so as not to confuse new users as to where to >> > >>> look for the greatest information. I know I found having the draft >> > >>> manual, alter ego, cookbook, source code etc. to look at for answers >> > >>> quite confusing (though more is better than less, obviously). >> > >> > > -- >> > > Best Regards, >> > >> > > Paul Eden >> > >> > > "...and a little looking out for the other guy too." >> > > - Mr. Smith >> >> > > > > -- Best Regards, Paul Eden "...and a little looking out for the other guy too." - Mr. Smith --~--~---------~--~----~------------~-------~--~----~ 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 -~----------~----~----~----~------~----~------~--~---
