edit: I have changed the blog title, which was not correct in English, thanks Maik

I wanted to react on Martinj’s blog to make things clear about Pycon FR

Background

First of all here’s a little background about Pycon FR.

Afpy (Association Francophone Python) is a french Python user group created four years ago. The group counts around 100 members and is the only one of this size in french-speaking countries as far as we know. It has members from France, Belgium, Canada and North Africa countries.

Many meetings are organized throughout the year, mainly in Paris, and sometimes in Charleroi in Belgium.

An important event took place at the “Cité des sciences” in Paris last summer, called “Journées Python” We had around 80 attendees and a rich program was given during two days. Topics where presented by french speaking people from France and Belgium, and we had talks about AI, Django, Zope, TuxDroid, etc

Some videos are available on the web, you can probably reach them from here: http://video.google.fr/videosearch?q=journees.afpy.org

The conference was 100% free for attendees. We also decided to chose carefully the dates so the conference would not compete with other events like Europython.

This event was a *true* success.

This event is now called Pycon FR, to be in the same line of what happens in some other countries. This makes a lot of sense indeed, to have national Python events, with standardized names.

Attendees

Pycon FR attendees are mainly people that speaks english but for some of them not enough to easily follow English talks. Most of those people would not make it to Europython because of this language barrier, and a national conference held in Paris is something that was quite missing at this time, for them.

So PyCon FR is just a sign of the growing interest about Python, and should be seen as a 100% positive and constructive thing, believe me.

Together with Europython and Pycon US, the “local” PyCons are in my opinion, a very good thing to spread the good word. We will, like last year, promote Europython there. Maybe we could even do a survey this year to know exactly who goes to Europython, etc.

Pycon FR expansion plans

When I said in my last blog entry that we were working on making it less french-centric, and having international attendees, I should have explained it better to make sure no one thinks Pycon FR might be a bad thing for Europython.

• If we do invite international speakers, it will be done only if we are able to provide a live translation system.
• The event date will always be picked carefully, as usual, so it does not compete with Europython.

Europython and local PyCons expansion

Here’s my opinion about what Europython strategy could be: since it is an international english-speaking event that gathers a lot of people. It could be the seed to set up a local Pycon event in places where it does not exist yet, using the momentum of the event.

This could be done by working with the local user group this way, by organizing maybe two years in a row Europython there. So, maybe we could see “Pycon Lithunia” next year ? Then move EuroPython to Amsterdam and see “Pycon The Netherlands” in two years ?

Europython exists to promote the language at an international level, so that could be a good way to spread imho.

But please, pretty please, don’t see local Pycons as Europython competitors, this is not true, this happens just because Python is growing.

Everyone should be happy about that I think. I disagree with the fact that each conference might fight to have the “best international speakers” for a very simple reason: the number of speakers is growing too, and I don’t think either Pycon either EuroPython will ever miss of interesting talks.

The next smart move I think is to organize and synchronize all these events, and that is where the Python Software Foundation has a role to play in my opinion. They have started anyway, and I am really confident about what will happen next.

Ben Bangert was reacting about zc.buildout doctests, saying that they are hard to read from the PyPI page, and the examples hard to use and follow.

I agree with Ben as these doctests are very hard to read when you are not familiar with zc.buildout testing modules, which provides a set of API the doctests relies on.

But from a developer point of view, adding a feature to such a package is best done through doctests, using zc.buildout.testing goodies. And a developer that is familiar with this package, will find this doctest very useful.

zc.buildout in any case, is trying to structurize its PyPI front page, and push a maximum amount of doc for users, so … kudos !

I think the problem is more about specifying the target readership.

I would like to point another example that comes in zc.buildout: dependency-links.

The main doctest that appears at PyPI as a light, human-readable section: http://pypi.python.org/pypi/zc.buildout#dependency-links

And the very same section is continued in a specific doctest that does not appear on the main page: http://svn.zope.org/zc.buildout/trunk/src/zc/buildout/dependencylinks.txt?rev=81182&view=markup

So what happened here is that the developer specified two kind of readers:

• people that will reach the package through its PyPI page
• people that will go deeper in how the package works, through recipes or tutorials

From there I think there’s a simple guideline that could be applied to enhance the package documentation when adding a feature:

• resume the feature in the main page (long_description) with examples that does not rely on specific testing API. In other words it should be made of plain english and plain python when needed;
• leave doctest that relies on internal testing API as complementary documentation.
• define for each doctest its nature (recipe, tutorial, etc)

How could we help people doing such structuration ?

The distutils metadata could be a good place to do it, by adding an extra_doctests list for example, that would contain a list of doctests. From there, PyPI could display the long_description text as usual, and add a “more information section”.

Let’s take an example:

def _(f)
return open(f).read()

setup('my.package', ...
long_decription=_('README.txt'),
extra_description=
{'recipe': [_('create_this.txt'),
_('do_that.txt')],
‘tutorial’: [_('how_to_use.txt')
_('how_to_2.txt')]}

From there, PyPI could provide a Table of content, with a structurized documentation, and additional pages for the package, grouped by types (recipe, tutorial) etc. -> Maybe a Sphinx-powered PyPI ?

By the way, I have another post related, which tries to summarized good pratices in technical writing : http://tarekziade.wordpress.com/2007/02/23/technical-writing-the-seven-laws

Last year, I worked on a documentation builder based on doctest and reStructuredText format called PyCommunity. This tool is collecting doctests from Python packages and from special places on a source repository, basing its work on a set of project good practices I had presented and used in a Pycon 2007 tutorial (slides).

Basically, it uses the best practices described in Andreas Ruping book, called Agile Documentation, applied to Python projects using TDD and doctests. It can be called Document-Driven Development.

I have never found the time to finish the tool and I was looking forward to get back to it. As a matter of fact, George Brandl has released the tool that is used to generate Python documentation, called Sphinx, which does many things I still have in my TODO list, like pygments integration, and many other things.

See how Sphinx generates Python doc here: http://docs.python.org/dev

From there, it becomes dead simple to generate a website for a Python project, based on packages doctests and text files and on a specific doc/ structure.

Sphinx annoucement is really exciting, and it shouldn’t be too much pain to bundle it in a buildout recipe to manage a project documentation. Since it is based on templates and configuration files, a default structure can be generated to startup a project documentation together with a code base.

I have to try and see if Sphinx allows me to set everything up. In other words, replay my Pycon tutorial with it.