Sphinx autodoc dies on ImportError of third party package

Question

There's any way to exclude the import part of a module and then document it with sphinx-python? I have a module that imports another package (other different project) and then the sphinx gives this error:

""" File "/usr/local/lib/python2.7/dist-packages/Sphinx-1.1.3-py2.7.egg/sphinx/ext/autodoc.py", line 321, in import_object import(self.modname) File "/home/x/GitHub/project/mod_example1.py", line 33, in from other_pck import Klass, KlassStuff ImportError: No module named other_pck """

And if I comment the import parts in the module that calls/imports that package the sphinx can do the autodoc. I tried with all the sphinx autodoc modules: autoclass, automodule, etc... but the result is always the same once it try's to import the other package.

Thanks

score 4 · Accepted Answer · edited Dec 14 '13 at 18:48

You are fixing the issue wrong way. The correct way to fix the issue is to make Sphinx aware of your existing other packages as autodoc functionality must import Python packages to scan the source code. Python packages cannot be imported without all their dependencies resolved and you cannot cherry-pick lines of source code out of it, because this is how Python is built(*)

Possible solutions are

Creating a Python virtualenv environment where both Sphinx and the other packages reside, so that they can see each other http://opensourcehacker.com/2012/09/16/recommended-way-for-sudo-free-installation-of-python-software-with-virtualenv/
Setting PYTHONPATH environment variable or editing sys.path in Sphinx config file, so that missing packages are added in the import list when Sphinx is run http://scienceoss.com/minimal-sphinx-setup-for-autodocumenting-python-modules/

*) In theory you can, but this is outside the scope of Sphinx and this question

Thanks for your answer! This somehow solves my problem locally, but still remains in readthedocs. I use the requirements.txt but it doesn't get and install the other project to the virtualenv correctly. Maybe it's something with readthedocs. Bests — Bjorn Nunskt, Mar 06 '13 at 15:19
I suggest ask help on #readthedocs IRC channel on freenode network — Mikko Ohtamaa, Mar 06 '13 at 20:59

score 0 · Answer 2 · answered Nov 24 '22 at 16:26

Sometimes it's due to the machine that you're using to generating docs does not have the third party package imported by the python project. For example, there isn't pytorch on my current machine to write the docs. You can mock the required packages by adding the following in conf.py

autodoc_mock_imports = ['packages', 'to', 'mock']

In my case, its

autodoc_mock_imports = ['torch']

See this blog for detail.

Sphinx autodoc dies on ImportError of third party package

2 Answers2

Linked