On Sat, Feb 28, 2009 at 10:47 AM, Paul Eden <benchl...@gmail.com> wrote:
> 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. Yes!!! Yes!!!! In fact, this is what I like about http://www.djangobook.com/en/2.0/chapter01/ and have thought, and talked in the past w/ those who wrote this one-off. Other possiblities: - rietveld like reviews, but for the document (Guido's tool which runs on appspot; it's a django app, an could be ported and adapted perhaps - I haven't look at it enough to form an opinion, but know that for Android / Google project, they are using a java (!) modified version of rietveld - gerrit2; so I think we could do something like this -- there are potential code submisstion process that this could extent to for web2py; for example, Android only allows "push" into repostory by the review tool, when there is review by team, and signoff by section owners; ) - wiki like submission of changes (text only versioning and viewing) to the "source" pages right from sphinx - this, tied with a review tool might be the best way to have a "live" sphinx project in the beginning. > - 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. Thanks for the link. In my mind, this blog-comment style (at first glance) seems too busy. > > - In my mind that site has 3 main advantages. > 1. All of the documentation is there in one place. I think all the main documentation in one place is a good thing; I think carrying to "all documentation" - taking it too far could make it less usable... > > 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 Thanks Paul! Yarko > > > > 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 -~----------~----~----~----~------~----~------~--~---
