sphinx-build fail - autodoc can't import/find module

Question

I\'m trying to get started with Sphinx and seem to have relentless problems.

Command: docs/sphinx-quickstart

I answer all the questions and ever

Answer 1

You can use Pweave and noweb formatting to generate rst documents that include the output of the code embedded in them. Basically, you write your rst file, with python code embedded in marked chunks like this:

<<echo=False>>=
print("some text that will appear in the rst file")
@

and Pweave will execute those chunks, and replace them with their output in a resulting rst file, which you can then use with sphinx. See the Pweave reST example for more details of how it looks.

Answer 2

Autodoc can't find your modules, because they are not in sys.path.

You have to include the path to your modules in in the sys.path in your conf.py. Look at the top of your conf.py (just after the import of sys), there is a sys.path.insert() statement, which you can adapt.

By the way: you can use the Makefile created by Sphinx to create your documentation. Just call

make

to see the options.

If something went wrong before try:

make clean

before running make html.

Answer 3

If

1. module root path is correctly set in conf.py
2. __init__.py is placed correctly
3. rst syntax is correct

and your autodoc still cannot find the modules...

It may be because the dependencies of those modules are not satisfied under your python environment. You will want to check if all the import statements are working within the modules.

Answer 4

I don't know why (maybe in my case autodoc couldn't install my package), but I always got module-not-found errors until I explicitly included all directories containing modules to the path.

For the following example folder structure

project_dir
|- setup.py
|- src
|  |- __init__.py
|  |- source1.py
|  |- sub_project
|     |- __init__.py
|     |- source2.py 
|- docs
    |- conf.py
    |- source
    |  |- index.rst
    |- _build       

I included

for x in os.walk('../../src'):
  sys.path.insert(0, x[0])

to the beginning of conf.py such that all involved directories would be added.

Answer 5

I think I did this the first time I tried to add a file to the toctree. I think it was because I left out the blank line between the :maxdepth line and the file name.

.. Animatrix Concepts documentation master file, created by
   sphinx-quickstart on Thu Mar 22 18:06:15 2012.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to Animatrix Concepts documentation!
============================================

Contents:

.. toctree::
   :maxdepth: 2

   stuff


Indices and tables
==================

* :ref:`genindex`
* :ref:`modindex`
* :ref:`search`

Above is my index.rst file. stuff.rst resides in the same directory as it.

Answer 6

in conf.py

just add the path to your project folder.

sys.path.append('/home/workspace/myproj/myproj')