# Fix autodoc_mock_imports not suppressing autodoc import errors

## TL;DR

Mocking only works when the list names top-level packages: autodoc_mock_imports = ['torch'] intercepts 'import torch' and everything under it, but ['torch.nn'] does not. List the top-level names (and confirm autodoc is actually enabled), then rebuild. The import warning clears because the import machinery is intercepted before your code runs.

## The error

```text
docs/api.rst:4: WARNING: autodoc: failed to import module 'mypackage'; the following exception was raised:
No module named 'heavylib'
```

## Steps

1. In conf.py, confirm both lines exist: `extensions` includes `sphinx.ext.autodoc`, and `autodoc_mock_imports` is set. Without the extension, the mock setting is silently ignored.
   Expected: both are present.

2. Rewrite the list with TOP-LEVEL package names only: `autodoc_mock_imports = ["heavylib"]`, not `["heavylib.submodule"]`. Mocking the top level covers every submodule import beneath it.
   Expected: the list contains importable top-level names matching the warning's 'No module named' value.

3. Rebuild verbose and check: `sphinx-build -v -b html docs docs/_build 2>&1 | grep "failed to import"`.
   Expected: no output: the warning is gone.

## Use this when

- autodoc_mock_imports is set but 'failed to import module' persists
- the missing module is a heavy optional dependency (ML frameworks, DB drivers)
- the mock list contains dotted submodule paths

## Not for this skill when

- 'has no setup()' (extension loading fails before mocking matters)
- import errors for your own package (fix sys.path; mocking your own code hides real breakage)
- attribute errors inside docstrings (the import worked; the object is wrong)

## Variant phrasings

- sphinx autodoc_mock_imports not working
- autodoc mock imports failed to import module persists
- sphinx mock heavy dependencies autodoc
- autodoc_mock_imports submodule not mocked

## Why it happens

autodoc_mock_imports installs fake modules into sys.modules before autodoc imports your code, but Python's import system consults sys.modules by top-level name first: mocking 'heavylib' makes 'import heavylib.sub' resolve through the fake, while mocking only 'heavylib.sub' leaves the real top-level import to fail. The setting is also read only when the autodoc extension is active, which is why a missing extension entry makes the whole list a no-op.

## Edge cases

- Mocks stub the import, not behavior: code that subclasses a mocked class or calls mocked functions at import time can still fail; that needs a real install or restructuring the import behind a function.
- Never mock stdlib modules or modules your Sphinx extensions themselves import; you will break the build in confusing ways.
- Mocked objects render with limited signatures in the docs; for public API pages prefer a real install and reserve mocks for genuinely heavy optional dependencies.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_vP1tzQcUlTxZB59IBWhong