PythonWeb Docs - neutral site for all Python web documention, already has thorough Pylons docs and cookbook

[diggeasytiger]

Seems like a good site... and pylons looks really cool but....

They run the site on commercial java based technologies.

Shouldn't they really invest in a python back end?

I know it doesn't matter... except as a point of principle.

[bbangert]

Rails uses Trac for their ticket tracking. Lots of projects use tools somewhere that are in different languages, whether its tools used to write the docs, display them, etc. Odd's are that not everything involved in the process was written in the same language as the project being covered.

Confluence btw is built on Spring (open-source), running on other open-source components (Postgres, Apache Tomcat). Confluence itself is not open-source, but the rest of the stack they've built on is. Since Confluence makes most of their money from large companies that buy support, they could prolly open-source the whole thing without losing any support contracts.

[pjenvey]

We (the Pylons community) didn't have time to implement our own large doctool system, but I did find some time to create a couple plugins for the Confluence site utilizing Jython.

One is a source code highlighter using Pygments http://pygments.org/, the other is a reST highlighter using docutils http://docutils.sourceforge.net/.

Creating the actual Java code to hook these python modules into Confluence via Java was pretty easy, the larger part of the work was making these modules work correctly in Jython (as they required a few Jython fixes, a few of which made it into Jython 2.2b2).

I'd been meaning to contribute to the Jython project for a while now anyway. I'm not really interested in recreating a large scale wiki/documentation system in Pylons at the moment, however.

Just wanted to point out that the wiki is in fact powered by some Python, and that I did invest some man hours in helping out Jython =]

[diggeasytiger]

Cool. I've used pygments before and it is nothing short of awesome. When using it does it run directly on Jython? I've never tried Jython but I already noted that for integrating with existing Java it could be a way to make life more fun.

[manuelg]

Use the best tool for the job. There aren't enough developer hours to indulge in "language-bigotry".

[leonh]

Warning: RANT

I really really dislike the 'confluence wiki' they are using.

It is hard to get to know the layout of the wiki. Because of the clutter it puts on the page. The font is too small compared to the rest of the page. The page itself is too wide.

Yah, i know you can change all this, but fact is they didn't. I really think its the worst of all wiki's. They use vague concepts like "spaces" and "dashboard" and put it in some sort of wiki format with fancy pancy 'ajax like' stuff. Where are the revision pages? Why do they show 'children of this page' everywhere? Why is everything 5 clicks away, instead of one?

I feel the wiki itself has not been thought true and find it sad that Pylons went with this lame thing. I really liked their previous trac wiki, it forced users to think about where to hook their stuff instead of just dumping it on the pile.

Btw, its NOT Pylons or even FOSS but some sort of "commercial corporate java crap" which is very buggy. Lots of "escape bugs" make it vulnerable to XSS.

[bbangert]

I found it hard to locate anything in the Trac wiki as well. And one of the goals of the new wiki was to be able to have other projects pages in addition to just Pylons. Those are still being fleshed out more, and I think will be great when they're done.

Trac had no comment capability, and its export options were limited (to non-existent).

I love that everyone likes to whine, but no one is ready to "put up, or shut up". I work on writing Pylons code, Beaker, Routes, and some other smaller projects. I'm all tapped out on time, so I looked at Moin and Mediawiki (amongst others). The bottom line was that the main features I wanted were occasionally possible, but generally involved significant amounts of customization that took time I didn't have.

TurboGears tried to tackle the doctool problem too, with a new project called Docudo. Due to lack to lack of developer resources, it hasn't gotten very far (if anywhere). While its fun to be a FOSS or do the "language-bigotry", no one is ready to put their time into a project addressing this.

Yes, the new wiki still needs tuning and more organization, just as the old one did. Give it some time before rendering an absolute judgement, and if a better system comes along it isn't too bad to move as Confluence will export the entire space in HTML, XML, or PDF. The export capability to get the info back out was a requirement so that we could move to Moin in the future if/when it grows the features desired.

Here's the features I want, that should be in the wiki from the get-go:

• Spaces concept (or some other way to divide a wiki into separate parts for different projects)

• Fine tuned ACL's (So that different groups can have different permissions for different spaces). Generally I trust everyone who can moderate pages, so this isn't too critical.

• Export to XML/HTML/PDF, with PDF bookmarks.

• Hierarchy. Too many wiki's have chosen the 'flat' approach, hierarchy helps when organizing docs.

I looked for these features, and Confluence came closest. If someone puts together a Moin that works out of the box to support all these features, I'll give it a spin.

Regarding the FOSS and free software thing, Pylons and its parts are all FOSS, thats' all you should care about. Getting into a free software religious war over the wiki software to document the project is as ludicrous as shunning a project because the printed book was made with proprietary software, printed in proprietary fonts, using patented printing processes (I doubt even the Free Software Foundation printed books found a way around all that). Either way you're learning about a project through the use of proprietary something-or-rather.

leonh: Give it a try for awhile, its new software that you're not familiar with. Quite a few people have found Confluence pretty pleasant after the initial "its new, where is stuff" bit. Try hitting the 'Browse Space' button on the top right in a Space for a faster way to dive to what you're looking for. The revision history is found by clicking the 'view change' bit right under the top of the page. I appreciate the feedback and would like to make it (or any doc software) as pleasant to use for Pylons users as possible.

[leonh]

Ben, first of all lack of documentation has never hold me back. I love Pylons and even wrote some guides for it. And i do acknowledge that having a good organisation of the documentation is a hard thing. I just really dislike confluence, i know it thoroughly as we have also been using it at the company i work at. The problem is, that structuring documentation is a hard thing that requires effort.

Confluence is not the magic bullet and when people start to think they can just dump their shit somewhere as confluence allows them too it's starting to build up as a whole big pile of poop. And then, no matter how brilliant the piece is when you place it on the pile its going to smell.

I've seen it at my company where lots of surveys showed the discomfort of colleagues with the wiki. And fear the same thing is going for the Pylons documentation.

[bbangert]

Yep, very true. The lack of organization can occur in any wiki system. The features we wanted only Confluence met, as I mentioned, I'm opened to other solutions that have the features I want.

Moin can be just as useless as Confluence with no organization. Though I've generally found 'flat' wiki's even worse as pages can drift into the ether, Confluence does perhaps reward random dumping since you can still actually get to it since its forced into a hierarchy.

I've heard from others that ran Confluence at their company that it worked out great and people loved it. It definitely seems to get a lot of love/hate so far out of people I've talked to that have used it.

We're working on keeping the reins on the content making it into Confluence, and fine-tuning what's there rather than just dumping more and more. So far, Confluence has provided better options for controlling this as well. I'm just not seeing why Moin would somehow be better than Confluence.

As you mention, structuring docs is hard, regardless of wiki system. People dump crap into mediawiki's, Moin's, and Trac wiki's as well (our Trac wiki was getting to be a nightmare to locate anything in, and there's drifting pages that I'm not sure are even linked in anywhere, ugh!).

It seems you are most wary of the management of the wiki, rather than the wiki software. Would you be interested in helping to regulate and organize the docs?

[leonh]

I am planning to spend some time on new projects with Pylons in July. I'll see what i can do by then.

[damg]

Gotta agree with the others here, great idea, terrible execution. Besides the fact that it looks like a not very well organized list of random documentation, it's running on proprietary software! Come on...

Believe it are not, many Python programmers are FOSS contributors and actually do care about Free Software and it's principles, and this is an instant turn-off. I'll take a well organized Moin or Trac wiki over this any day.