PickleError in Sphinx 1.2

Now lets start giving some tips and tricks:

Trying to build documentation with Sphinx 1.2 for Stalker I got the following message:

PicklingError: Can't pickle : attribute lookup sqlalchemy.ext.declarative.api.Base failed

Last year I was also having this same error message and I've solved it by downgrading to Sphinx 1.1.3. But this time I wanted to solve it.

Because I'm not deeply informed about the internals of Sqlalchemy, it didn't catch my attention at the first glance but if you look at the module sqlalchemy.ext.declarative.api you will find nothing about the Base that Sphinx is complaining about.

So I've figured out that my Base class that I'm generating with sqlalchemy.ext.declarative.declarative_base() ends up being referenced from that module.

So the following lines were creating the problem:

from sqlalchemy.ext.declarative import declarative_base

class ORMClass(object):
    """The base of the Base class
    """
    pass

Base = declarative_base(cls=ORMClass)    

The solution was to add the following lines to the Sphinx conf.py:

import sqlalchemy.ext.declarative.api
from stalker.db.declarative import Base
sqlalchemy.ext.declarative.api.Base = Base

Now at the build time of the docs there will be a Base in the api module, and it will not mess my library cause it is in Sphinx' conf.py..