How to ignore 'src' directory in python project when making sphinx autodoc

(alternative description could be 'how to rename a sphinx-autodoc package name?')

using sphinx version 1.7 on Python 2.7.13

I would like to automatically create documentation using docstrings and sphinx-apidoc.

My project structure is as follows:

myPythonProject      <- my Python package name and git repository.
|-- docs
|   |-- _build
|   |   |-- html     <- where final HTML doc is created.
|   |   
|   |-- apidocs      <- contains the autodoc created '.rst' files.
|   |-- _static
|   |-- _templates
|   |
|   | conf.py        <- 4 Sphinx doc files, auto generated with sphinx-quickstart.
|   | index.rst      <-
|   | make.rst       <-
|   | Makefile       <-
|
|
|-- src
|   | __init__.py    <- important for 'setup.py'.
|   | myModule1.py
|   | myModule2.py
|   | myModule3.py
|
| setup.py

The myModule files contain docstrings.

After performing the sphinx-quickstart with quite standard options (extensions autodoc and intersphinx. No separated source and build directories. Adding make.bat and Makefile files.) And some minor change to the conf.py where I uncommented and changed:

# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.

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

When running: sphinx-apidoc -f -o docs/apidocs src

The docstrings are found but it is convinced src is my package name. It clearly does not observe my setup.py file or something. It does look at __init__.py though, if I remove it I can create docs with only modules, no package at all. But also this is not desired, but closer at least.

The content of src is installed as 'MyPythonProject'. Therefore Setup.py is configured as follows to install this package and leaving out the 'src' reference when importing:

from setuptools import setup

setup(
    name='MyPythonProject',

    packages={'MyPythonProject': 'src'},
    package_dir={'MyPythonProject': 'src'},

(Is this an unorthodox structure? Otherwise I would also be interested in a more common layout which autodoc does support.)

Currently

sphinx-apidoc -f -o docs/apidocs src
sphinx-build -a -b html docs/ docs/_build/html

returns the following document: you can ignore the red.

Question

How can I create documentation showing myPythonProject.myModule1.def1() it's docstring, and not src.myModule1.def1()?

Solution

Another alternative would be to include src in your path and specify the module without the src prefix.

So change your path setup to the src folder by replacing your line above with this in docs/conf.py:

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

and in your sphinx index.rst change the automodule:: accordingly.

That way, you won't have that src. prefix to your class names.

Worked for me, anyway :-)