How to get autodoc to import packages that are locally written

Question

I have the following structure:

└──faulty_meter
    └── __init__.py
    └── run.py
    └── utils.py
    └── anomalous_kwh_detection
        └── __init__.py
        └── general_anomalies.py
        └── slowing_down.py
    └── docs
        └── Makefile
        └── build
        └── make.bat
        └── source
            └── conf.py
            └── index.rst

run.py imports utils.py and the files in anomalous_kwh_detection .

I run sphinx as follows from docs :

sphinx-quickstart
sphinx-apidoc -o ./source ..
make html

I get this warning: WARNING: autodoc: failed to import module 'run.py' from module 'faulty_meter'; the following exception was raised: No module named 'utils' WARNING: autodoc: failed to import module 'run.py' from module 'faulty_meter'; the following exception was raised: No module named 'utils' , which means autodoc can't find utils.py

I found a similar question here . I tried what was suggested, but could not really make it work.

In my case, what path should I include?

My conf.py file looks like this

import os
import sys
sys.path.insert(0, os.path.abspath('../../..'))
project = 'a'
copyright = '2021, b'
author = 'b'
release = '0.0.1'
extensions = ['sphinx.ext.autodoc','sphinx.ext.napoleon']
templates_path = ['_templates']
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store']
html_theme = 'sphinx_rtd_theme'
html_static_path = ['_static']

and my index.rst looks like this:

.. a documentation master file, created by
   sphinx-quickstart on Thu Aug 19 21:54:31 2021.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

Welcome to a's documentation!
=============================

.. toctree::
   :maxdepth: 6
   :caption: Contents:

   modules

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

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

Everything works nicely, except that run.py is ignored as indicated by the warning. How to fix that?

Edit: I attach an example of the generated documentation. It generates the documentation for utils correctly, but ignores run (it actually is run_anom_detection, but the name does not matter).

image

2nd Edit :

I'll provide a minimal reproducing example:

Let's have the following folder structure:

└──faulty_meter
    └── __init__.py
    └── run.py
    └── utils.py
    └── anomalous_kwh_detection
        └── __init__.py
        └── general_anomalies.py
    └── docs
        └── Makefile
        └── build
        └── make.bat
        └── source
            └── conf.py
            └── index.rst

Then utils.py can look like this

def test1(x, y):
    """
    This is just a quick test

    Parameters
    ----------
    x: array
       random array
    y: array
       another random array
    """
    return x+y

general_anomaly.py can look like this

def test2(x, y):
    """
    This is just a quick test

    Parameters
    ----------
    x: array
       random array
    y: array
       another random array
    """
    return x-y

and run.py can be

import utils
from anomalous_kwh_detection import general_anomalies as ga

def test_run(x, y, z):
    """
    This is the function that is not documented
    """
    p = utils.test1(x, y)+ ga.test2(y, z)
    return p

Answer 1

The issue here is the interpretation of import statements in Python packages. In run.py, you have:

import utils

This is an implicit relative import , which is not supported in Python 3.

It works if you change to either an explicit relative import ,

from . import utils

or an absolute import ,

import faulty_meter.utils as utils

The other statement in run.py will work if a dot is added:

from .anomalous_kwh_detection import general_anomalies as ga

Note: When python run.py is run from the command line, the code is not executed as part of a package and the imports specified above do not work. Instead you can use python -m faulty_meter.run .

References:

• How to accomplish relative import in python
• Relative imports for the billionth time
• https://chrisyeh96.github.io/2017/08/08/definitive-guide-python-imports.html