lucumr

Small notice for persons trying to mail me the last ~three days: While I was off to Vienna I noticed that HE disabled the E-Mail routing for the domains I moved to domainfactory. Mails send to me between Friday and today are probably lost.

I now uploaded the documentation for Jinja2 to the website for those of you who are eager and want to play with it :-) On jinja.pocoo.org you have now the choice to chose between Jinja1 and Jinja2.

The new docs are powered by Sphinx and Jinja2 with a custom templating bridge.

Read the documenation.

The TurboGears project has been accepted as a mentoring organization for the 2008 Google Summer of Code. Even if you’re not interested in TurboGears because your framework of choice is something else you might still be interested in that one as it includes two Genshi project ideas: Performance and Jython compatibility.

If you have a solid knowledge of XML/HTML, Python and you’re looking for a GSoC project that’s interesting, read Christopher’s blog post about it and go for it :-)

As mentioned in an earlier blog post I’m not a fan of full automatically generated documentation as I think it’s clearly the wrong way to solve documentation problems. Whenever I encounter epydoc generated documentation and I find out that that’s the only kind of documentation I run away :)

In the past there have been two kinds of documentation in the python world: handwritten documentation (Django for example) and full automated API documentation (Paste’s). Both of them have advantages and disadvantages for user and developer but none of them was perfect. At least for me. Django’s documentation is one of the best I ever encountered but writing such documentation yourself is painful. I tried to do something similar with Werkzeug and Jinja and it sucks. On the one hand because usually you start improving stuff and add the documentation later on, often forgetting about it. It’s not unlikely that the documentation is slightly different from the actual implementation because someone (usually me) forgot to “sync” them.

With Werkzeug 0.2 I was experimenting with combining those two things. I added some directives to docutils that pulled docstrings automatically from the objects and added them to the rst file. That way the documentation is perfectly in sync with the sourcecode and because the members are specified explicitly I can hide implementation details and private functions. However the Werkzeug documentation builder was and is a hack and was never meant to be used by anyone except the Werkzeug project, and even that one just for one release. The reason for that is that Georg Brandl spent the last couple of weeks rewriting and improving parts of the python documentation tool which powers the new Python 2.6 and 3.0 docs to support non cpython projects too.

The resulting library Sphinx is in my opinion the best general purpose documentation tool since sliced bread! It’s intended to be a tool for handwritten documentation that builds a documentation into standalone HTML files, CHM HTML files, LaTeX or pickles which can be used to display the documentation in a WSGI application.

It uses reStructuredText as markup language for all the documentation, supports syntax highlighting of code blocks via pygments, embedded doctests so that you can extend your testsuite with doctests from your documentation, has support for automatic object documentation by including the docstrings from objects listed (semiautomated documentation as I did with Werkzeug), automatic cross linking, index generation, changelog generators, many custom roles and directives for rst and much more.

While it’s the first release it’s already a very good documented and well tested library and used for the Python documentation. While I hate the word “framework” I think Sphinx could be that for documentation tools. The extension API can be used to add missing features and may also be used for more automated documentation generation in the future.

Unfortunately I wasn’t that active in the implementation of Sphinx so far, so I’m clearly the wrong person for further questions about the development direction of Sphinx but I’m sure Georg will answer your questions. You can contact him in #pocoo on irc.freenode.net or via E-Mail at georg guesswhichcharcomeshere python dot org.

Links:

• Sphinx Homepage
• Sphinx in the Cheeseshop
• Georg’s blog

TextPress has now a dedicated development blog. That means two things. For one development on TextPress is active again and we are looking for help on converters, missing extensions (especially ATOM publishing support) and more.

That development blog is of course running on TextPress ;-)

May I introduce: GHRML, the Genshi Human readable markup language. name not final of course, mika would kill me ^^.

What’s GHRML? First of all it’s work in progress. But beside that it’s a pretty cool clone of Haml for Python. But no, it’s not another templating language, just a different representation for genshi markup templates. This way we can reuse all the genshi features like the directives or serializers. This gives you the full capabilities of the genshi templating language in a nice alternative syntax.

So how does it look like? Here a small example:

%html
  %head
    %title Hello World
    %style{'type': 'text/css'}
      body { font-family: sans-serif; }
    %script{'type': 'text/javascript', 'src': 'foo.js'}

  %body
    #header
      %h1 Hello World
    %ul.navigation
      %li[for item in navigation]
        %a{'href': item.href} $item.caption

    #contents
      Hello World!

Most of the syntax is directly stolen from Haml. The only real change is that we don’t need explicitly marked self closing elements because genshi knows that already in the serializer. Additionally you can use brackets for genshi directives like the for-loop above. And the parser works with variable indentation, if you want an indention level of four, just do so, the parser will recognize that.

Sourcecode in the sandbox for those of you who want to try it, some updates later ;-)

Wohoo. Werkzeug 0.2 is out now. Werkzeug started as simple collection of various utilities for WSGI applications and has become one of the most advanced WSGI utility modules. It includes a powerful debugger, full featured request and response objects, HTTP utilities to handle entity tags, cache control headers, HTTP dates, cookie handling, file uploads, a powerful URL routing system and a bunch of community contributed addon modules.

So, what’s new in 0.2? Countless things and too many for this small list, but here the most important ones:

• The path converter limitation is gone. rejoice!
• In the contrib package there is now a secure cookie (basically a hashed a client side session storage)
• Exceptions can now return response objects so that you can add headers etc.
• You can now convert a response object to a different type of response objects on the fly (for example if you have your own response object subclass with special features but the response object returned by a function is a simple BaseResponse)
• There are a bunch of extra features for response and request objects now (available as mixin classes) for HTTP header parsing and dumping
• All the routing exceptions are now HTTPExceptions which simplifies dispatching a lot
• werkzeug.script has a much simpler way of specifying boolean parameters
• lazy_property is now called cached_property, update your code!
• many cool small helper functions that deal with python modules and packages. There is find_modules which can return a generator for all the modules below a package and import_string which allows you to simply import objects from a string. No more __import__ hackery needed.
• the usage of the map adapter is much easier now too and a lot more rest compliant. See the new documentation
• dozens of small fixes and additions!

There is also a new website and documentation and the tutorial was translated to German. For 0.3 we hopefully have some more translations for the tutorial and a better documentation for the contrib modules which are currently just documented in docstrings.

Grab it from the cheeseshop while it’s hot.

The last four days I attended our first offline-webteam meeting and it was fun ;-) We spend a few days hacking on various parts of the ubuntuusers software and had a great time. While it’s pointless to talk about what we did because hacking on broken code is not that much fun as such (unless you can laugh about PHP bugs and stuff like that) I think we can present some of the changes with the upcoming hardy release.

Don’t expect too much but that shows that we are doing something even if you think development on the German portal software is stalled. That’s certainly not the case.

But we are once again looking for web designers. The sourcecode is multilingual and the development takes place in both German and English for potential future translations to other languages than German, so you can participate even if you are not speaking German :-) If you are interested in participating and if you have advanced XHTML1/HTML4/CSS2 skills, we want you for ubuntuusers webteam!

If you are interested mail me at mitsuhiko you know what comes next ubuntu dot com.

Currently on pocoo.org is a semi static webpage with a completely unmaintained semi static blog and completely outdated information. While pocoo is not dead yet (just resting) it’s time to put something on the front page that represents the current state of the situation in a better way.

Let’s see if we can get that updated in the next two weeks. Oh, and TextPress is now up to date again, a bunch of bugs were fixed and we’re much nearer to a release than some weeks ago, but unfortunately we’re behind the roadmap once again :-)

I now installed the Werkzeug example applications on pocoo.org. So you don’t have to pull all the code if you want to try them out :-)

Here is the Wiki and the Planet. Have fun testing.