mkdocstrings not finding module

Question

I've hit a bit of a wall with the mkdocstring plugin as it does not seem to load modules as I would have expected.

My folder structure is as such:

docs/
  api.md
src/
  module/
    somemodule.py

The api.md file looks like this:

# API Documentation

::: module.somemodule.MyClass
handler: python

The error I get is this:

% mkdocs build                                                                                                                                                                     1 ↵ ✹
INFO     -  Cleaning site directory
INFO     -  Building documentation to directory: /site
ERROR    -  mkdocstrings: No module named 'module'
ERROR    -  Error reading page 'api.md':
ERROR    -  Could not collect 'module.somemodule.MyClass'

What I have found in testing:

• mkdocs runs correctly, generating the expected documentation when excluding the mkdocstrings plugin.
• mkdocstrings plugin works only if I move mypackage to the repo root

Is there some kind of config setting I need to set with the plugin in the mkdocs.yml to get it to recognize the module in the src folder? All the example I have come across seem to either be outdated or don't work.

Answer 1

I faced this same issue today, turns out there was an error in the py file. I had a function definition returning multiple things,

# this gave me the error
def foo(x) -> x,y: 
  # some logic
  pass

# this fixed the problem for me
from typing import Union
def foo(x) -> Union(x,y): 
  # some logic
  pass

Look for any syntax or typing based errors, that should probably fix your problem.

Answer 2

Since your package lives under the src folder, you might need to configure the Python handler of mkdocstrings so that it can find it, see https://mkdocstrings.github.io/python/usage/#paths and https://mkdocstrings.github.io/python/usage/#finding-modules.

plugins:
- mkdocstrings:
    handlers:
      python:
        paths: [src]  # search packages in the src folder

Answer 3

Installing the optional python dependency fixed it for me -

pip install 'mkdocstrings[python]'