For Java there is Javadoc, for Perl there is perldoc, and for Python there is pydoc.

I haven’t played around with pydoc too much, I usually use online documentation or read documentation in source code files. Last week I wrote some code that used PyCha to plot a few datasets, and not only did that experience make me realize that PyCha has a severe lack of documentation, but also that pydoc generates HTML that looks like something from the last century.

First of all - it doesn’t look that great visually, the colors and the layout is a little bit off. Improving on this could make it more appealing to developers.

Second - the HTML output is using nasty things like the font element and lots of tables for non-tabular data. Separating layout and content makes it much easier for other people to implement their own designs, so restructuring the HTML and using CSS should fix this.

Instead of just ranting about it, I decided to take action and see what could be done about it.

The result? Something that so far looks a lot cleaner then the old version (let me know if the new version looks like crap in IE, I haven’t had a chance to test with it). This is not complete, though. There is still work remaining: the style needs to be improved further to make it easier to navigate, and it might be useful to add more navigation elements.

Most importantly, though: the HTML code is a lot cleaner and easier to style. One exception, though… Currently a base64 encoded Python logo is included in every file. I did this because I wanted some visual elements, but I still wanted it to be self-contained.

The focus today has been cleaning up the HTML, design comes later. If you’re wondering why it doesn’t validate, it’s because it’s HTML5, which we like a lot.

A patch for the Python trunk is available.

Update: changed more layout and expanded the menu at the top in the latest version. Think I’m on the right track.