I've also been wondering if some sphinx macro type thing might be a valid approach for this, but might easily be more trouble than it is worth.

As for ``__doc__`` and config, if you move it to the Extension class then the "problem" would be solved. So then the module level docstring could just be a general high level intro, think one or two short sentences to show what this is for, and then the Extension gets all the details.