Can `python.apigen` be used for documenting global variables?

[peske]

First, thanks for the great work!

Here's the example of a variable (type annotation) that I would like to document:

NpVector: TypeAlias = np.ndarray[np.float64, Tuple[int]]
"""Shorthand annotation for float NumPy vector of floats.

Group
-----
    Type annotations
"""

Is this possible to accomplish in any way? Directly, or some workaround... Any help will be appreciated!

[jbms]

I think this is not currently supported by Sphinx:

https://github.com/sphinx-doc/sphinx/issues/11561

The best solution would be to fix upstream in Sphinx. I'm not sure what workarounds might be possible.

[2bndy5]

In the past, I've used autodoc's autodata:

.. autodata:: my_module.GLOBAL_MEMBER

I've never tried documenting a TypeAlias in this way though. Note that the autodata directive especially supports an :annotation: option which might be useful to you.

[mhostetter]

The way I accomplished this in one of my libraries is the following.

The resulting webpage: https://mhostetter.github.io/galois/latest/api/galois.typing.ArrayLike/

The variable declaraition: https://github.com/mhostetter/galois/blob/a140a468fa1f7619f94ad2551f9c14e684ee3a34/src/galois/typing.py#L92

[peske]

Thanks very much for trying to help! I like @mhostetter solution the most, but I still cannot make it work :(

Can you please take a look at my setup to check what I'm missing? Here are the key parts of my project:

• <project_root>/grc/typing.py module:

"""Defines some custom type annotations."""

from typing import TypeAlias

from nptyping import Float64, NDArray, Shape

# noinspection PyUnresolvedReferences
NDSquareMatrix: TypeAlias = NDArray[Shape["Size, Size"], Float64]  # noqa: F821
"""Shorthand annotation for NumPy square matrix of floats.

Group
-----
    Types
"""

But when I try to build the doc, I'm getting the following error:

Extension error (sphinx_immaterial.apidoc.python.apigen):
Handler <function _builder_inited at 0x7fde1faa0540> for event 'builder-inited' threw an exception (exception: Cannot set values to nptyping.NDArray.)
make: *** [Makefile:20: html] Error 2

Am I doing something wrong, or it is a bug?

Thanks!

[peske]

Actually, I've given up on introducing these type aliases anyway, so my problem (at this moment) went away. Feel free to close this one. I'm leaving it open only because it describes a potential bug.

Thanks for trying to help!

[2bndy5]

If it is a bug, it isn't specific to this theme, rather Sphinx itself.

[peske]

If it is a bug, it isn't specific to this theme, rather Sphinx itself.

@2bndy5 not sure how you've concluded that having in mind that the error arises in the extension of this theme:

Extension error (sphinx_immaterial.apidoc.python.apigen)

But anyway, it's your call...

[jbms]

There is a limitation in the built-in autodoc extension that our apigen extension depends on. However, the fact that our extension raises an exception is a bug that we should address.

Can you provide a minimal complete self-contained example that reproduces the exception issue?

[peske]

@jbms Sure, will do tomorrow (not close to a comp now...)

[peske]

@jbms As promised, here's a minimal project that reproduces the error: https://github.com/peske/sphinx-immaterial-bug