Question

I am trying to link my Sphinx documentation with ReadtheDocs. I can build the documentation locally but when I try to have ReadtheDocs automatically generate the documentation I get the following error:

Sphinx Standard Error

Making output directory...

Exception occurred:
  File "/var/build/user_builds/mousedb/checkouts/latest/Docs/source/conf.py", line 25, in <module>
    from mousedb import settings
ImportError: No module named mousedb
The full traceback has been saved in /tmp/sphinx-err-n_8fkR.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
Either send bugs to the mailing list at <http://groups.google.com/group/sphinx-dev/>,
or report them in the tracker at <http://bitbucket.org/birkenfeld/sphinx/issues/>. Thanks!

My project name is mousedb. I don’t understand why I get this import error in the auto-build but not locally.

Update

Based on the comments I think that this is an issue for importing my settings file into a sibling Docs directory. Rather than doing an absolute import (as I had been doing) I should be doing a relative import based on the location of settings.py and conf.py.

I want to import my settings file into my conf.py with the following directory structure:

-mousedb
--settings.py
-Docs
--source
---conf.py
--build

Answer 1

You originally talked about a “local absolute path to my code” and now about setting up relative paths to your code. This probably means you’re not using a setup.py file and also not a virtualenv.

In the same directory as Docs/ and mousedb/, add a setup.py:

from setuptools import setup

setup(name='mousedb',
      version='0.1',
      description="My sample package",
      long_description="",
      author='TODO',
      author_email='[e-mail]',
      license='TODO',
      packages=['mousedb'],
      zip_safe=False,
      install_requires=[
          'Django',
          # 'Sphinx',
          # ^^^ Not sure if this is needed on readthedocs.org
          # 'something else?',
          ],
      )

After committing/pushing/whatever this file, you can go to your readthedocs settings for your project. Enable the “use virtualenv” setting. This will “nstall your project inside a virtualenv using setup.py install”.

The end result is that everything python-related that readthedocs does will have your project in it’s sys.path.

The probable cause of your problems is that you run sphinx from within your “root” directory on your local system, where python magically finds the mousedb/ package in your current directory. But readthedocs apparently runs it from within the Docs/ directory and thus cannot find mousedb.