Add warning message for unresolved python elements

[arwedus]

Observed behavior

In an rst file with content like:

Autodoc Directives
==================

.. autoapimodule:: example
    :members:
    :noindex:

Non-existing code references
----------------------------

.. autoapifunction:: test_example.bar_test

Where example is an existing python module in autoapi_dirs, and test_example.bar_test is just something I fabulated, sphinx-build -W -b html will happily run through with no warnings.

The resulting HTML page has an empty section "Non-existing code references", i.e. the broken code import is silently ignored.

Expected behavior

sphinx-autoapi emits a warning for every unresolvable code import.

Steps to reproduce

I have added a self-contained example and the list of installed packages.

I tried with sphinx-autoapi 3.0.0 and sphinx-autoapi 2.0.0, and sphinx 7.2.6.

Would be happy to learn if this is a bug or intended behavior. As this is definitely unwanted in our project, I would like to learn how to add a warning for unresolveable imports.

python-autoapi-example.zip

[AWhetter]

I've haven't checked this yet but I think that it's a behaviour of autodoc. The manual directives are built on top of autodoc, and therefore we inherit some of the behaviour that autodoc has. Unfortunately, I think that this is one of those behaviours.

[arwedus]

@AWhetter : I've checked now. When I use .. automodule:: example, it warns as expected:

WARNING: autodoc: failed to import module 'example'; the following exception was raised:
No module named 'example'

This happens in: https://github.com/sphinx-doc/sphinx/blob/cb8a28dd7e11a7a0a5bc9694163fc164433e2f36/sphinx/ext/autodoc/importer.py#L163

I think the problem occurs with sphinx-autoapi because it doesn't use the import method of the autodoc classes, but instead does a lookup in env.autoapi_objects. And if that lookup fails, there is no warning.

[arwedus]

@AWhetter : I've added the warning as a feature. When running tests on sphinx-autoapi locally, the warning showed when building the docs, and raised my attention that the API documentation is actually missing from this page: https://sphinx-autoapi.readthedocs.io/en/latest/reference/templates.html

So, you see how useful this warning feature is :-)