Question

I am trying to start documenting an small Python project with Sphinx.

I created a samplecode.rst where I would try to organize (and auto-generate) the documentation for one of my classes (MyClass.py).

This is part of that samplecode.rst:

MyClass.py
----------------------------------
.. autoclass:: backlib.classes.MyClass
   :members:

But when I try to execute make html, I get an Import Error and the ‘MyClass‘ is not imported (showing an empty entry for ‘MyClass‘ in the generated .html):

Traceback (most recent call last):de                                                                                                                                                                                
  File "/usr/lib/pymodules/python2.7/sphinx/ext/autodoc.py", line 329, in import_object
    __import__(self.modname)
  File "/home/borrajax/Projects/myProject/backlib/classes/MyClass.py", line 4, in <module>
    from backlib.database import BaseClass
[ ... ]
    from grokcore.component import sort_components
ImportError: cannot import name sort_components

… and a bit later…

/home/borrajax/Projects/myProject/docs/source/samplecode.rst:16: (WARNING/2) autodoc can't import/find module 'backlib.classes.MyClass', it reported error: "cannot import name sort_components", please check your spelling and sys.path

/home/borrajax/Projects/myProject/docs/source/samplecode.rst:19: (WARNING/2) don't know which module to import for autodocumenting u'MyClass' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)

That grokcore thing that is messing up with my life is a module that gets installed in $HOME/.buildout/eggs/ and that I haven’t created nor I need to document.

I have added all the eggs found in $HOME/.buildout/eggs/ to the Pythonpath (in the Sphinx’s conf.py file) but that didn’t fix anything so now I’m trying a different approach (giving up) so here goes the question: Can I do something to skip this kind of errors?

I just want the comments in /home/borrajax/Projects/myProject/backlib/classes/MyClass.py to show in a pretty html page, that’s all.

Answer 1

Well… I found the issue.

Mike Steder’s answer confirmed something that I had started suspecting by googling around: This type of ImporErrors in Sphinx are usually fairly trivial errors of some kind of misconfiguration. Nothing too intricate, so eventhough I had the directory where my source code was located in the sys.path (as Mike suggests in his answer), I started digging around.

I commenced speculating that something I had done was messing up with the PythonPath, and the only thing I had actually done was adding the .eggs found in $HOME/.buildout/ through Sphinx’s conf.py file (so there had to be something wrong with that). I checked my $HOME/.buildout/ directory and realized that an update of the main Web Framework (Grok) used in this project had downloaded new versions of the .eggs to the $HOME/.buildout/ directory (causing most of the .eggs to have two versions). I removed completely the .buildout directory and reinstalled the Grok project (which downloaded the required .eggs, again, but now I don’t have multiple versions of the same .egg).

And now, Sphinx’s make html creates a nice entry for my MyClass class 🙂