bug: Symlinks are not followed to find `.pyi` files

[kylebarron]

Description of the bug

I use mkdocstrings in obstore, and it works great. obstore exposes the Rust object_store crate, for accessing S3/GCS/Azure storage.

However, accessing S3/GCS/Azure is useful for many Rust-Python libraries. I wrote obstore in such a way that third parties can reuse the underlying Rust code to re-export Python classes to build underlying Rust ObjectStore instances. Since Rust-Python FFI is unstable, these classes have to be re-exported by each library that wishes to use them. (So each Python package will have a store module that contains the exported code)

I'm writing another Rust-backed Python library, https://github.com/developmentseed/async-tiff, which also needs to access cloud data, and so which re-exports the Python classes implemented by obstore from Rust.

In order to re-export the type hints as well, I have a symlink from the Python folder which points into a git submodule referencing obstore.

vscode is able to follow this symlink correctly:

(Here, all of this information is provided in the upstream git submodule ).

And the Python code imports correctly.

However mkdocstrings fails to import:

ERROR   -  mkdocstrings: async_tiff.store.from_url could not be found
ERROR   -  Error reading page 'api/store/index.md':
ERROR   -  Could not collect 'async_tiff.store.from_url'

Note that mkdocstrings succeeds at finding these .pyi files when these are not symlinks (the upstream obstore documentation works, and those are not symlinks).

To Reproduce

git clone https://github.com/developmentseed/async-tiff
cd async-tiff/python
git checkout 81b73834a1ec52043f132aa2cff8edcad8758064
git submodule update --init --recursive
uv sync --no-install-package async-tiff
uv run --no-project maturin develop
uv run --no-project mkdocs serve

Full traceback

Full traceback

> uv run --no-project mkdocs serve
INFO    -  Building documentation...
INFO    -  FutureWarning: The 'import' key is renamed 'inventories' for the Python handler
             File
           "/Users/kyle/tmp/async-tiff/python/.venv/lib/python3.12/site-packages/mkdocstrings/handlers/base.py",
           line 682, in get_handler
               self._handlers[name] = module.get_handler(**kwargs)
             File
           "/Users/kyle/tmp/async-tiff/python/.venv/lib/python3.12/site-packages/mkdocstrings_handlers/python/handler.py",
           line 370, in get_handler
               warn("The 'import' key is renamed 'inventories' for the Python handler",
           FutureWarning, stacklevel=1)
INFO    -  Cleaning site directory
ERROR   -  mkdocstrings: async_tiff.store.from_url could not be found
ERROR   -  Error reading page 'api/store/index.md':
ERROR   -  Could not collect 'async_tiff.store.from_url'

Aborted with a BuildError!

Expected behavior

Expected to be able to follow symlinks to find documentation in .pyi files.

Environment information

> uv run --no-project python -m mkdocstrings_handlers.python.debug
- __System__: macOS-15.3.1-arm64-arm-64bit
- __Python__: cpython 3.12.7 (/Users/kyle/tmp/async-tiff/python/.venv/bin/python3)
- __Environment variables__:
- __Installed packages__:
  - `mkdocs` v1.6.1
  - `mkdocstrings` v0.28.2
  - `mkdocstrings-python` v1.16.2
  - `griffe` v1.5.7

Additional context

[pawamoy]

Hi @kylebarron, thanks for the report! I was able to confirm thanks to your share repo and instructions (thanks 🙏), and also found the solution: we should simply add followlinks=True to our os.walk call 🙂

[pawamoy]

Fixed in Griffe 1.6.0 🙂

[kylebarron]

Thanks! I can confirm this is working!