Failed to import module when building the sphinx documentation

Question

I'm using Sphinx version 1.4.5.

My project structure is the following:

+ src > main.py + docs (generated with sphinx-quickstart)

Even after adding the path to the src folder in docs/conf.py:

sys.path.insert(0, os.path.abspath('../src'))

And generating the rst file for src/main.py (i.e. docs/src.rst and docs/modules.rst) with:

$ sphinx-apidoc -fo docs src

When I try to build the html webpages with:

$ make clean
$ make html

It couldn't find both the src module and src/main.py:

WARNING: autodoc: failed to import module u'src.main'; the following exception was raised

No it's the parent of both `src` and `docs` (i.e. the project folder). — Hakim, Aug 15 '16 at 22:04

score 6 · Answer 1 · answered Apr 07 '20 at 13:07

I like to use the following code in conf.py to know exactly what the current directory is and where is the target module (to obtain documentation):

current_dir = os.path.dirname(__file__)
target_dir = os.path.abspath(os.path.join(current_dir, "../../src"))
sys.path.insert(0, target_dir)

print(target_dir)

In this case, I'm looking to create documentation for my src, see the tree for context:

main
├── docs
│   ├── build
│   ├── make.bat
│   ├── Makefile
│   └── source
│       ├── conf.py
│       └── index.rst
│ 
└── src
    ├── __init__.py
    ├── target_module
    ├── requirements.txt
    └── setup.py

Next, from your terminal:

[user@localhost docs]$ sphinx-apidoc -f -o source/ ../src/target_module
[user@localhost docs]$ make html

Plasma · Accepted Answer · 2016-08-15T23:20:47.093

5

Try doing this for your path insertion instead:

sys.path.insert(0, os.path.abspath('../'))

Also consider a better name for your directory than src.

edited Aug 15 '16 at 23:20

answered Aug 15 '16 at 22:10

Plasma

2,369
1
29
35

The `conf.py` was generated directly inside the `docs` folder. What do you suggest to use instead of `src`? – Hakim Aug 15 '16 at 22:13
3

See my update for what you should try if `conf.py` is inside `docs`. wrt directory naming, it's common practice to name your source directory the same as the project - so if your project is called Foobar, have a directory `foobar` instead of `src`. – Plasma Aug 15 '16 at 23:21

score 0 · Answer 3 · answered Aug 15 '16 at 22:06

0

Your current working directory should be the directory of your makefile, which should be docs.

answered Aug 15 '16 at 22:06

Laurent LAPORTE

21,958
6
58
103

2

What do you mean exactly by working directory? Do you mean the directory where I execute `sphinx-apidoc` and `make`? – Hakim Aug 15 '16 at 22:12
@Hakim yes, in your example it is `./docs/` – Yogev Neumann Nov 25 '22 at 19:38

Failed to import module when building the sphinx documentation

3 Answers3

Linked