Issue with automodule and cython/numpy

[samuelmurail]

Describe the bug

Hello everybody,

I am trying to create the automodule section of my library (https://github.com/samuelmurail/pdb_numpy)

Analysis module
---------------

.. automodule:: pdb_numpy.analysis
   :members:
   :undoc-members:
   :show-inheritance:

But I get this warning, and the automodule docs is not created:

making output directory... done
[autosummary] generating autosummary for: basic_example.md, index.rst, installation.md, modules.rst, pdb_numpy.alignement.rst, pdb_numpy.data.rst, pdb_numpy.format.rst, pdb_numpy.rst, pdb_numpy.tests.rst, readme.rst
WARNING: Failed to import pdb_numpy.analysis.
Possible hints:
* TypeError: numpy.dtype is not a type object
* AttributeError: module 'pdb_numpy' has no attribute 'analysis'
WARNING: Failed to import pdb_numpy.tests.test_alignement.
...
reading sources... [100%] readme
WARNING: autodoc: failed to import module 'analysis' from module 'pdb_numpy'; the following exception was raised:
Traceback (most recent call last):
  File "/home/murail/miniforge3/envs/docking/lib/python3.10/site-packages/sphinx/ext/autodoc/importer.py", line 69, in import_module
    return importlib.import_module(modname)
  File "/home/murail/miniforge3/envs/docking/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/home/murail/Documents/Code/pdb_numpy/src/pdb_numpy/analysis.py", line 10, in <module>
    from . import alignement
  File "/home/murail/Documents/Code/pdb_numpy/src/pdb_numpy/alignement/__init__.py", line 9, in <module>
    from . import align_cython
  File "src/pdb_numpy/alignement/align_cython.pyx", line 1, in init pdb_numpy.alignement.align_cython
TypeError: numpy.dtype is not a type object

Im my cython library align_cython.pyx I have put #cython: embedsignatures=True and cnp.import_array():

#cython: infer_types=True
#cython: boundscheck=False
#cython: wraparound=False
#cython: linetrace=True
#cython: embedsignatures=True 

###cython: profile=True

import cython
import numpy as np
cimport numpy as cnp

# It's necessary to call "import_array" if you use any part of the
# numpy PyArray_* API. From Cython 3, accessing attributes like
# ".shape" on a typed Numpy array use this API. Therefore we recommend
# always calling "import_array" whenever you "cimport numpy"
cnp.import_array()

This error happen when I use autodoc_mock_imports = ["numpy", "scipy", "pytest"]

If I install numpy, and remove numpy from autodoc_mock_imports then the automodule is build.

Is it expected to install numpy to build the documentation ? Should I add numpy to sphinx requirements.txt ?

Cheers, Thanks for your help.

How to Reproduce

sphinx-build -M html "source" "build"

Environment Information

sphinx>=6.1.3
sphinx-argparse>=0.4.0
sphinx_rtd_theme>=1.2.0
nbsphinx>=0.9.1
numpydoc>=1.5.0
myst_parser>=1.0.0

I also try with this versions:
sphinx>=7.3
sphinx-argparse>=0.4.0
sphinx_rtd_theme>=2.0.0
nbsphinx>=0.9.4
numpydoc>=1.7.0
myst_parser>=3.0.0

Sphinx extensions

extensions = [
    'sphinx.ext.autodoc',
    'sphinx.ext.coverage',
    'sphinx.ext.todo',
    'sphinx.ext.viewcode',
    'sphinx.ext.githubpages',
    'sphinx.ext.todo',
    'sphinxarg.ext',
    'sphinx.ext.mathjax',
    'numpydoc',
    'myst_parser']

Additional context

No response

[jayaddison]

Hi @samuelmurail - thanks for the report.

Is it expected to install numpy to build the documentation ?

Generally it is the case that when Sphinx builds Python-based documentation, it reads and evaluates the Python code files within the project.

So in general, it is necessary for your project's Python code to evaluate successfully, including resolution of module imports, etc. As you've found, there are some options to allow mocking-out individual imports in cases where it isn't desirable to have those installed at doc-build-time.

I'm not hugely familiar with cpython, but my guess is that the cimport statement is not mocked out by autodoc_mock_imports -- and that when it is evaluated, it attempts to load some numpy Python modules that you don't have available, causing the module's evaluation (and then your Sphinx project build) to fail.

[jayaddison]

I'm not certain that this is a bug, so I'm going to remove the label and relocate this thread into the GitHub discussions area until we confirm either that this is in fact a bug, or perhaps figure out a feature request / enhancement proposal from it.