Sphinx autodoc can't find code modules

Issue #523 resolved
Ben Finney created an issue

The Sphinx ‘autodoc’ extension expects to import the code modules, in order to generate API documentation.

The Sphinx configuration currently does not specify where to find the code modules for import. This means that when Make does not have the expected current directory (a normal occurrence), ‘autodoc’ complains:

/build/python-coverage-4.2+dfsg.1/doc/api_coverage.rst:13: WARNING: autodoc: failed to import class 'Coverage' from module 'coverage'; the following exception was raised:
Traceback (most recent call last):
  File "/usr/lib/python3/dist-packages/sphinx/ext/autodoc.py", line 519, in import_object
    __import__(self.modname)
ImportError: No module named 'coverage'

The resulting documentation has no content where the API documentation should be.

This can be fixed by:

  • Configuring Sphinx specifically to find the code modules, relative to the documentation directory. This will correct the above error, but does not address the more general assumption of current directory during the build process.

  • Detecting the current directory at Make time, and computing the directories needed for the various commands Make invokes.

The latter is the more robust and general solution. GNU Make sets the ‘CURDIR’ variable to the current working directory; this allows reliably computing relative paths for commands.

For your convenience, when GNU make starts (after it has processed any -C options) it sets the variable CURDIR to the pathname of the current working directory.

Comments (6)

  1. Ned Batchelder repo owner

    You haven't shown me how you a producing this error. Also, I suspect you have an idea of how to fix it? :)

  2. Loic Dachary

    Here is a reproducer on a fresh checkout of 24aff3d7bfd5 and a fresh virtualenv

    $ make docreqs dochtml
    pip install -r doc/requirements.pip
    Requirement already satisfied: pyenchant==1.6.8 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from -r doc/requirements.pip (line 5))
    Requirement already satisfied: sphinx==1.4.9 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from -r doc/requirements.pip (line 6))
    Requirement already satisfied: sphinxcontrib-spelling==2.2.0 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from -r doc/requirements.pip (line 7))
    Requirement already satisfied: sphinx_rtd_theme==0.1.9 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from -r doc/requirements.pip (line 8))
    Collecting doc8==0.0 from git+https://github.com/nedbat/doc8.git#egg=doc8==0.0 (from -r doc/requirements.pip (line 11))
      Cloning https://github.com/nedbat/doc8.git to /tmp/pip-build-Ed3BEj/doc8
      Requested doc8==0.0 from git+https://github.com/nedbat/doc8.git#egg=doc8==0.0 (from -r doc/requirements.pip (line 11)), but installing version 0.7.1.dev1
    Requirement already satisfied: six>=1.5 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: docutils>=0.11 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: Pygments>=2.0 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: imagesize in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: babel!=2.0,>=1.3 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: snowballstemmer>=1.1 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: Jinja2>=2.3 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: alabaster<0.8,>=0.7 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: chardet in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from doc8==0.0->-r doc/requirements.pip (line 11))
    Requirement already satisfied: restructuredtext-lint>=0.7 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from doc8==0.0->-r doc/requirements.pip (line 11))
    Requirement already satisfied: stevedore in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from doc8==0.0->-r doc/requirements.pip (line 11))
    Requirement already satisfied: pytz>=0a in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from babel!=2.0,>=1.3->sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: MarkupSafe in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from Jinja2>=2.3->sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: pbr>=1.8 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from stevedore->doc8==0.0->-r doc/requirements.pip (line 11))
    Installing collected packages: doc8
      Found existing installation: doc8 0.7.1.dev1
        Uninstalling doc8-0.7.1.dev1:
          Successfully uninstalled doc8-0.7.1.dev1
      Running setup.py install for doc8 ... [?25ldone
    [?25hSuccessfully installed doc8-0.7.1.dev1
    sphinx-build -b html -a -E doc doc/_build/html
    Running Sphinx v1.4.9
    Initializing Spelling Checker
    ** Prerelease = False
    building [mo]: all of 0 po files
    building [html]: all source files
    updating environment: 18 added, 0 changed, 0 removed
    reading sources... [100%] trouble
    /home/loic/software/coveragepy/issue-523/coverage.py/doc/api_coverage.rst:13: WARNING: autodoc: failed to import class u'Coverage' from module u'coverage'; the following exception was raised:
    Traceback (most recent call last):
      File "/home/loic/software/coveragepy/issue-523/v/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 529, in import_object
        __import__(self.modname)
    ImportError: No module named coverage
    /home/loic/software/coveragepy/issue-523/coverage.py/doc/api_coverage.rst:25: WARNING: autodoc: failed to import function u'process_startup' from module u'coverage'; the following exception was raised:
    Traceback (most recent call last):
      File "/home/loic/software/coveragepy/issue-523/v/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 529, in import_object
        __import__(self.modname)
    ImportError: No module named coverage
    /home/loic/software/coveragepy/issue-523/coverage.py/doc/api_coveragedata.rst:15: WARNING: autodoc: failed to import class u'CoverageData' from module u'coverage'; the following exception was raised:
    Traceback (most recent call last):
      File "/home/loic/software/coveragepy/issue-523/v/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 529, in import_object
        __import__(self.modname)
    ImportError: No module named coverage
    /home/loic/software/coveragepy/issue-523/coverage.py/doc/api_plugin.rst:19: WARNING: autodoc: failed to import class u'CoveragePlugin' from module u'coverage'; the following exception was raised:
    Traceback (most recent call last):
      File "/home/loic/software/coveragepy/issue-523/v/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 529, in import_object
        __import__(self.modname)
    ImportError: No module named coverage
    /home/loic/software/coveragepy/issue-523/coverage.py/doc/api_plugin.rst:26: WARNING: autodoc: failed to import class u'FileTracer' from module u'coverage'; the following exception was raised:
    Traceback (most recent call last):
      File "/home/loic/software/coveragepy/issue-523/v/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 529, in import_object
        __import__(self.modname)
    ImportError: No module named coverage
    /home/loic/software/coveragepy/issue-523/coverage.py/doc/api_plugin.rst:33: WARNING: autodoc: failed to import class u'FileReporter' from module u'coverage'; the following exception was raised:
    Traceback (most recent call last):
      File "/home/loic/software/coveragepy/issue-523/v/local/lib/python2.7/site-packages/sphinx/ext/autodoc.py", line 529, in import_object
        __import__(self.modname)
    ImportError: No module named coverage
    looking for now-outdated files... none found
    pickling environment... done
    checking consistency... done
    preparing documents... done
    writing output... [100%] trouble
    generating indices...
    writing additional pages... search
    copying static files... done
    copying extra files... done
    dumping search index in English (code: en) ... done
    dumping object inventory... done
    build succeeded, 6 warnings.
    
    Build finished. The HTML pages are in doc/_build/html.
    
  3. Loic Dachary

    It's fixed by installing the coverage like so

    (v) loic@fold:~/software/coveragepy/issue-523/coverage.py$ pip install -e .
    Obtaining file:///home/loic/software/coveragepy/issue-523/coverage.py
    Installing collected packages: coverage
      Running setup.py develop for coverage
    Successfully installed coverage
    (v) loic@fold:~/software/coveragepy/issue-523/coverage.py$ make docreqs dochtml
    pip install -r doc/requirements.pip
    Requirement already satisfied: pyenchant==1.6.8 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from -r doc/requirements.pip (line 5))
    Requirement already satisfied: sphinx==1.4.9 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from -r doc/requirements.pip (line 6))
    Requirement already satisfied: sphinxcontrib-spelling==2.2.0 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from -r doc/requirements.pip (line 7))
    Requirement already satisfied: sphinx_rtd_theme==0.1.9 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from -r doc/requirements.pip (line 8))
    Collecting doc8==0.0 from git+https://github.com/nedbat/doc8.git#egg=doc8==0.0 (from -r doc/requirements.pip (line 11))
      Cloning https://github.com/nedbat/doc8.git to /tmp/pip-build-NUCaYS/doc8
      Requested doc8==0.0 from git+https://github.com/nedbat/doc8.git#egg=doc8==0.0 (from -r doc/requirements.pip (line 11)), but installing version 0.7.1.dev1
    Requirement already satisfied: six>=1.5 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: docutils>=0.11 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: Pygments>=2.0 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: imagesize in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: babel!=2.0,>=1.3 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: snowballstemmer>=1.1 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: Jinja2>=2.3 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: alabaster<0.8,>=0.7 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: chardet in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from doc8==0.0->-r doc/requirements.pip (line 11))
    Requirement already satisfied: restructuredtext-lint>=0.7 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from doc8==0.0->-r doc/requirements.pip (line 11))
    Requirement already satisfied: stevedore in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from doc8==0.0->-r doc/requirements.pip (line 11))
    Requirement already satisfied: pytz>=0a in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from babel!=2.0,>=1.3->sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: MarkupSafe in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from Jinja2>=2.3->sphinx==1.4.9->-r doc/requirements.pip (line 6))
    Requirement already satisfied: pbr>=1.8 in /home/loic/software/coveragepy/issue-523/v/lib/python2.7/site-packages (from stevedore->doc8==0.0->-r doc/requirements.pip (line 11))
    Installing collected packages: doc8
      Found existing installation: doc8 0.7.1.dev1
        Uninstalling doc8-0.7.1.dev1:
          Successfully uninstalled doc8-0.7.1.dev1
      Running setup.py install for doc8 ... [?25ldone
    [?25hSuccessfully installed doc8-0.7.1.dev1
    sphinx-build -b html -a -E doc doc/_build/html
    Running Sphinx v1.4.9
    Initializing Spelling Checker
    ** Prerelease = False
    building [mo]: all of 0 po files
    building [html]: all source files
    updating environment: 18 added, 0 changed, 0 removed
    reading sources... [100%] trouble
    looking for now-outdated files... none found
    pickling environment... done
    checking consistency... done
    preparing documents... done
    writing output... [100%] trouble
    generating indices...
    writing additional pages... search
    copying static files... done
    copying extra files... done
    dumping search index in English (code: en) ... done
    dumping object inventory... done
    build succeeded.
    
    Build finished. The HTML pages are in doc/_build/html.
    (v) loic@fold:~/software/coveragepy/issue-523/coverage.py$ 
    
  4. Ned Batchelder repo owner

    I still don't see how to reliably reproduce this problem. It happened the first time I tried "make docreqs dochtml", and then I couldn't make it happen again, even with "make clean". But you guys seems to think this fixes it, so OK!

  5. Log in to comment