sphinx autoclass not importing module

Question

At the risk of being told I didn't research this enough (I have been at this for the goodpart of a week now), I can't get the autoclass feature to work in sphinx. I get a range of import errors. I've added both sys.path.insert(0,os.path.abspath('.')) sys.path.insert(0, os.path.abspath('..')) to the conf.py file so that shouldn't be the reason, as I've tried a whole host of other files too.

I've made a small example repo here: GitHub

But the jist is this:

In a repo of the structure:

funniest
   funniest
      __init__.py
      text.py
      text2.py
   doc
      source
         index.rst
         text.rst
         text2.rst

Where text.py and text2.py contain simple classes like so:

class Sad(object):
    """Not so funny class
    """
    def sad_story(self):
        """This is a sob story
        """
        print('This is a very sad story')


    def sad_story2(self):
        """This is a sob story 2
        """
        print('This is a very very sad story')

and text.rst is:

Sad
===

Sad story

.. autoclass:: text.Sad
   :members:

I don't understand why it doesn't work. Clearly I'm missing something but I find the sphinx doc's (ironic for a documentation package) really hard to follow for examples that go beyond trivial and aren't super complicated either.

Any help as to where the issue lies would be much appreciated.

Answer 1

First, always paste the error stack to make less work for those who would answer, like so:

$ make html
sphinx-build -b html -d build/doctrees   source build/html
Running Sphinx v1.6.3
['/Users/stevepiercy/projects/funniest_example/funniest/doc', '/Users/stevepiercy/projects/funniest_example/funniest/doc/source', '/Users/stevepiercy/projects/funniest_example/funniest/env/bin', '/Users/stevepiercy/.pyenv/versions/3.6.1/lib/python36.zip', '/Users/stevepiercy/.pyenv/versions/3.6.1/lib/python3.6', '/Users/stevepiercy/.pyenv/versions/3.6.1/lib/python3.6/lib-dynload', '/Users/stevepiercy/projects/funniest_example/funniest/env/lib/python3.6/site-packages', '/Users/stevepiercy/projects/funniest_example/funniest']
loading pickled environment... failed: Can't get attribute 'WarningStream' on <module 'sphinx.util.nodes' from '/Users/stevepiercy/projects/funniest_example/funniest/env/lib/python3.6/site-packages/sphinx/util/nodes.py'>
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 3 source files that are out of date
updating environment: 3 added, 0 changed, 0 removed
reading sources... [100%] text2
WARNING: /Users/stevepiercy/projects/funniest_example/funniest/doc/source/text.rst:6: (WARNING/2) autodoc: failed to import class 'Sad' from module 'text'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/stevepiercy/projects/funniest_example/funniest/env/lib/python3.6/site-packages/sphinx/ext/autodoc.py", line 657, in import_object
    __import__(self.modname)
ModuleNotFoundError: No module named 'text'
WARNING: /Users/stevepiercy/projects/funniest_example/funniest/doc/source/text2.rst:6: (WARNING/2) autodoc: failed to import class 'Jokes' from module 'funniest.text2'; the following exception was raised:
Traceback (most recent call last):
  File "/Users/stevepiercy/projects/funniest_example/funniest/env/lib/python3.6/site-packages/sphinx/ext/autodoc.py", line 657, in import_object
    __import__(self.modname)
  File "/Users/stevepiercy/projects/funniest_example/funniest/funniest/__init__.py", line 2, in <module>
    from . import text2
  File "/Users/stevepiercy/projects/funniest_example/funniest/funniest/text2.py", line 10
    """Shitty joke
    """

      ^
IndentationError: expected an indented block
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
writing output... [100%] text2
generating indices... genindex
writing additional pages... search
copying static files... WARNING: html_static_path entry '/Users/stevepiercy/projects/funniest_example/funniest/doc/source/.static' does not exist
done
copying extra files... done
dumping search index in English (code: en) ... done
dumping object inventory... done
build succeeded, 3 warnings.

Build finished. The HTML pages are in build/html.

The warnings say exactly what is wrong. The first one:

WARNING: /Users/stevepiercy/projects/funniest_example/funniest/doc/source/text.rst:6: (WARNING/2) autodoc: failed to import class 'Sad' from module 'text';

...says that in text.rst you have an incorrect import at line 6. So change this:

.. autoclass:: text.Sad

to this:

.. autoclass:: funniest.text.Sad

The second warning:

WARNING: /Users/stevepiercy/projects/funniest_example/funniest/doc/source/text2.rst:6: (WARNING/2) autodoc: failed to import class 'Jokes' from module 'funniest.text2'; the following exception was raised:

...says that text2.rst could not "import class 'Jokes'", and continues...

      File "/Users/stevepiercy/projects/funniest_example/funniest/funniest/text2.py", line 10
    """Shitty joke
    """

      ^
IndentationError: expected an indented block

...which means that in text2.py , the Python interpreter expected more indentation after the method definition at line 10. So indent the return statement of the method.

Once you fix those two errors, you should be good.

Bonus tip #1: use a code editor that checks your Python syntax for simple errors. I like PyCharm. It marked up your code with all kinds of red and yellow flags.

Bonus tip #2: You don't need any import statements in your __init__.py . It can be blank.