Sphinx is now used by quite a few communities : Python, Django, Pylons, Grok (not sure about the current status), …

No wonder, it’s a blast.

We are now starting to use it to produce customer documentation for our buildout-based applications. Basically, a Sphinx structure is created in the buildout using sphinx-quickstart, and a few tweaks are made so the HTML and PDF outputs have a custom look.

Managing the documentation like the code makes life easier. This is one of the basic rule of agile documentation : separate the content from the layout, so you can provide documentation in any shape (html, pdf) with a single source.

To make things easier, I have released collective.recipe.sphinxbuilder.

This recipe:

• creates for you a Sphinx-based documentation in your buildout
• creates a single script in the bin folder to build the documentation with one command
• provides an extensive set of options to drive Sphinx from buildout

Adding it in your buildout is as simple as :

[buildout]
parts =
  sphinx

[sphinx]
recipe = collective.recipe.sphinxbuilder

I have also customized the look and feel of the output so it uses the Plone logo and a custom css. This is configurable from the buildout configuration file of course. By the way, if someone from the Plone community wants to improve the CSS, please dot it ! (I am not good at this )

Notice that if you use LaTex or PDF rendering, you will need to install pdflatex. Furthermore, the recipe script will not work under Windows unless you install a Linux-like environment, since it uses the Makefile provided by Sphinx. I guess MSYS+MinGW should make it work, but I didn’t try.

I am glad to see more work is happening for using z3c.form in CMF and Plone, and Daniel Nouri updated us this week with the latest changes. I just updated my buildout to use the new packages and got plone.z3cform 0.4 and plone.app.z3cform 0.3.2.

With the small API changes that happened, you can see below that there is less to write to expose the form in the Plone site (our ContactForm example from my
previous post):

# my.example/my/example/browser.py

import datetime
from zope import schema
import zope.component
import z3c.form

import plone.app.z3cform
from plone.app.z3cform import layout

from plone.i18n.normalizer.interfaces import IIDNormalizer

from my.example import interfaces
from my.example.contact import MyContact

class ContactForm(z3c.form.form.Form):
    """ Contact Form """

    fields = z3c.form.field.Fields(interfaces.IContactData)
    message_field = z3c.form.field.Fields(schema.TextLine(__name__ = 'message',
                                                          title=u"Message",
                                                          required=False)
                                          )
    fields += message_field

    ignoreContext = True

    @z3c.form.button.buttonAndHandler(u'Send', name='send')
    def handle_send(self, action):
        data, errors = self.extractData()
        if errors:
            self.status = z3c.form.form.EditForm.formErrorsMessage
            return

        # Add the contact data, if not in yet
        id = data['firstname'] + data['lastname']
        id = zope.component.queryUtility(IIDNormalizer).normalize(id)

        if id not in self.context.objectIds():
            self._name = id
            contact = MyContact(self._name, **data)
            self.context[self._name] = contact

        # Complete the code so it sends the message to the site admin...
        message = data['message']
        print "Message from %s %s (%s):\n%s" % (data['firstname'], data['lastname'], data['email'], data['message'])

        self.request.RESPONSE.redirect(self.context.absolute_url())

# New way to provide the wrapping View
ContactFormView = layout.wrap_form(ContactForm, label="Contact Form")

The related ZCML code does not change.
By the way, on my TODO list, is moving from ZCML to grokcore.component registration

Today I was writing a little documentation about Plone 2.5 in reaction to a first draft on workflow management by groups. My goal is not to write a document alone that will replace this draft but to imply its author. A this point a tool was missing until I remember we can use Google Docs application to share our ideas and write this document together.

We have shortly try out Google Docs and our first impressions are positive: each other can write in the same document and modification are reported in live on the other screen. Add a GTalk window or an IRC session to discuss and you have a very powerful tool.

The next step is to finish this document and to copy/paste it in Plone Documentation. I hope to do this tomorrow night.

Hey Limi, when will we embed this in Plone ;^)

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.

I am spending some time to update the Archetypes Developer Manual on plone.org/documentation, so I can move forward in contributing on other stuff in the Doc Team tasks list.

If you are also in the situation of updating some old AT-based product for Plone 3, this might be useful to you.

The current version of our manual, in the part discussing a sample AT product called InstantMessage, is missing:

• GenericSetup profile for setting types and subskins. This has been missing for a long time, so I decided to update it immediately.
• ZCML-based registration for things such as FS Directory Views or class permissions and factory, which the current version of CMF permits.

I started updating the “InstantMessage” package’s code in this branch.

What was needed: Mainly replacing the old ‘Extensions/Install.py’ code by the needed GenericSetup profile XML files:

• for content types:

• profiles/default/types.xml
• profiles/default/types/InstantMessage.xml
• profiles/default/factorytool.xml

• for the sub-skin: profiles/default/skins.xml

Then, you need a piece of code for loading the GenericSetup profile. You do that, nowadays, by adding a configure.zcml file at the root of the package with the following code:

<configure xmlns="http://namespaces.zope.org/zope"

       xmlns:genericsetup="http://namespaces.zope.org/genericsetup"

       i18n_domain="instantmessage" >

<genericsetup:registerProfile

       name="InstantMessage"

       title="InstantMessage"

       directory="profiles/default"

       description="Extension profile for InstantMessage sample AT content type."

       provides="Products.GenericSetup.interfaces.EXTENSION"

      />

</configure>

I think I can now update the manual to reflect the new setup code - pointing to a couple of GS-related tutorials that already exist on plone.org, and merge the updated branch of the code with the trunk so people can get this new version.

Next step: Introduce other ZCML-based registrations in the CMF/AT context. This update could wait for the “versions” feature support on plone.org so we add these details without loosing the text related to the old way of doing.