On Thu, Jul 30, 2009 at 4:55 AM, jug <j...@fantasymail.de> wrote: > Hello, > > René Dudfield wrote: > >> >> >> On Tue, Jul 28, 2009 at 8:39 PM, jug <j...@fantasymail.de <mailto: >> j...@fantasymail.de>> wrote: >> >> Hello, >> >> We are still working on the pygame website rewrite. I'm currently >> implementing a snippets >> app that should replace the cookbook section in the wiki. The code >> is handled as code, >> apart from the description. Thus, you can download the snippets >> directly as .py file. Then, >> its easier for everyone (who has an account) to add new snippets, >> to find useful snippets >> and to remember them. >> >> >> There's a cook book and code search for this now. This searches the 1000s >> of projects on the internet for each use. It's much better than a snippet >> section you decided on. >> > Well, I can add a google search, too, but seaching is not the main point > here. A wiki is not designed to manage code snippets. Surely its possible, > you could even manage projects in a wiki, just give each an own page. In my > opinion, a snippets app is more user-friendly. You have one snippet, one > description text and one author. If someone has a good tip, he should be > mentioned when sharing it with the community. Users can review the code and > tell in a comment if it helped them or not, if there is something to improve > etc. > I know, it may be new to you and not convince you directly, but while > development, I got a lot of useful tips and snippets from > http://www.djangosnippets.org/. > General tips, tutorials or other stuff can still be handled in the wiki. >
yes, I don't care. Feel free to start up a separate website for them. > > > Since comments will be reserved for registered users, number of >> spam comments and other >> waste content should decrease a lot. For the rest, we may have >> something like "mark as spam" >> buttons, so you can tell the site admins directly if you notice >> any spam. >> >> >> why do you get to decide this? Many of the valid comments are made >> without login, those would not exist if it required a login. >> > > Well, I discussed that with Marcus. I think that there will be more users > with an account (or more users, that actually already have an account, will > login) if there is more than just projects. Currently, you just login if you > want to edit a project, a wiki page or comment on a project. And you get > automatically logged-out. On the new site, its more worthwhile to log in, > and you can stay logged-in longer, if you don't log out. So most active > pygame users should have and account and it's really easy, you just need a > valid email address. > But besides that, to open comments for anonymous wouldn't be difficult > either. > Why don't you and Marcus work on a pgreloaded website then? > > > Documentation is another problem. I think, with the website >> rewrite, also the docs should >> modernized. AFAIK, The current system is something self-made that >> uses documentation thats >> already written in html. It blends htms and stlyle to one html >> file, so it is quite impossible to change >> the style or to include it to the rest of the site. I don't know >> how the comments work, but it looks not >> good. As well, it would be better to have some kind of api access >> or at least methodical urls to >> access documentation programmatically form the rest of the site, >> the apis or even the attached >> irc bot. >> >> >> You're completely wrong about the documentation system. I suggest you >> actually read it before commenting on it. >> > Yeah, sorry. It uses simple text files with an own simple structure and > markup. So, it's not as bad as I thought. But still bad. IMHO, bad enough to > be replaced. > It *is* something self-made, the html and css is *hardcoded* into the > generator script and therefore it *is* impossible to change easily. Finally, > the output *is* ugly and *invalid* ( > http://validator.w3.org/check?uri=http%3A%2F%2Fwww.pygame.org%2Fdocs%2Fref%2Fsurface.html > ). > > However, after some trial and error and some changes on the generator code, > I got the docs integrated into the website (used code from svn, so docs are > for pygame 1.9.0): > http://pygameweb.no-ip.org/docs/ > > So, if no one is interested in a more professional documentation system, we > should at least update the generator script to produce some more valid code, > use a simple template for html and css and become a bit more configurable. > I really don't see where you get off calling the current system unprofessional. > > > I don't know about all the possible documentation systems and >> generators, but sphinx[1] may be >> adequate. Further on, I'm not sure if documentation should include >> comments. I think it would be >> better to use the snippets section to show really useful code >> snippets (we could link against them >> from the online docs) and for other stuff the wiki. If there is >> really sth. missing in the docs, it should >> be added to them, so also users who download the docs an read it >> offline should see these additions. >> >> Next (maybe pre-final) testing phase will come soon, >> including the new snippets app and much more. >> >> >> The comments section is staying. >> > Why do you get to decide this (alone and without argumentation)? > I admit, some comments in the docs are really helpful, but I'd say that at > these few points it's because of vague documentation, and that you should > improve the docs there instead of just adding a comments > function. If necessary, add small examples of 2-5 lines or so to the docs > of particular functions or classes. If users understand documentation only > together with attached comments, documentation is bad and needs to > be improved. > > > Julian > This has already been discussed, that's why. Obviously the website has been like this for a while, so at some point you'd think there was a discussion about it already? Obviously the documentation should be improved from the doc comments... that's one of their main purposes.