Best way to handle imported type annotations?

[Hong Xu]

Hi all,

I have a question regarding typed annotations that are imported from internal modules. This occurs for projects that put actual implementations in internal modules, and only let public modules import necessary symbols.

For example, the pytest project has its implementation in _pytest subpackage: https://github.com/pytest-dev/pytest/tree/master/src/_pytest

And it imports public symbols from pytest/__init__.py: https://github.com/pytest-dev/pytest/blob/master/src/pytest/__init__.py

However, the type annotation in the document seems pretty messed. For example, in the doc of pytest.Function [1], one of the base classes is documented as "_pytest.nodes.Item". But this object is imported from pytest/__init__.py [2], and the base class should be documented as "pytest.Item" instead of "_pytest.nodes.Item".

I understand autodoc_type_aliases may help, but I would like to ask whether there's a more generic and consistent way to handle all these situations.

Thanks!

Hong

[1]: https://docs.pytest.org/en/stable/reference.html#pytest.Function

[2]: https://github.com/pytest-dev/pytest/blob/6a5d47a243d2ddbf92fca5e807cf1324d60cabb1/src/pytest/__init__.py#L32

[Komiya Takeshi]

Hi,

I have a plan to improve documentations for these imported members in
4.x. But I don't have enough time at present. Unfortunatley, there is
no good way to document them better, AFAIK.

Thanks,
Takeshi KOMIYA

2021年1月29日(金) 9:12 Hong Xu <ho...@topbug.net>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/f9d14454-a116-4b6a-bfae-5ba440426c04n%40googlegroups.com.