search

nv-morpheus / Morpheus

Morpheus SDK
Apache License 2.0
380 stars 142 forks source link

[DOC]: sphinx fails to document a type alias for `dict` #1956

Open dagardner-nv opened 1 month ago

dagardner-nv commented 1 month ago

How would you describe the priority of this documentation request

Critical (currently preventing usage)

Please provide a link or source to the relevant docs

https://github.com/nv-morpheus/Morpheus/blob/branch-24.10/python/morpheus/morpheus/utils/type_aliases.py

Describe the problems in the documentation

Attempting to document this alias:

TensorMapType = dict[str, NDArrayType]

Yields this error, which appears to be a variant of https://github.com/sphinx-doc/sphinx/issues/8493

sphinx.errors.SphinxWarning: /home/dagardner/work/morpheus/python/morpheus/morpheus/utils/type_aliases.py:docstring of builtins.dict:20:autosummary: failed to import clear.
Possible hints:
* ValueError: not enough values to unpack (expected 2, got 1)
* ModuleNotFoundError: No module named 'clear'
* KeyError: 'clear'
* AttributeError: module 'morpheus.utils.type_aliases' has no attribute 'clear'
* ModuleNotFoundError: No module named 'morpheus.utils.type_aliases.clear'; 'morpheus.utils.type_aliases' is not a package

Warning, treated as error:
/home/dagardner/work/morpheus/python/morpheus/morpheus/utils/type_aliases.py:docstring of builtins.dict:20:autosummary: failed to import clear.
Possible hints:
* ValueError: not enough values to unpack (expected 2, got 1)
* ModuleNotFoundError: No module named 'clear'
* KeyError: 'clear'
* AttributeError: module 'morpheus.utils.type_aliases' has no attribute 'clear'
* ModuleNotFoundError: No module named 'morpheus.utils.type_aliases.clear'; 'morpheus.utils.type_aliases' is not a package
ninja: build stopped: subcommand failed.

Changing the alias to use typing.Dict avoids the issue:

TensorMapType = typing.Dict[str, NDArrayType]

(Optional) Propose a correction

No response

Code of Conduct

dagardner-nv commented 1 month ago

I was able to repro the issue outside of Morpheus without any of our code in as simple of a repro as possible (https://github.com/dagardner-nv/repro_1956).

Through trial/error I was able to isolate the issue to the numpydoc extension, and opened up: https://github.com/numpy/numpydoc/issues/587