Sphinx: WARNING: Cannot resolve forward reference in type annotations of ...

[markheik]

Description

Sphinx build complains about the missing references.

Example WARNING when building docs:
WARNING: Cannot resolve forward reference in type annotations of "zhinst.toolkit.driver.devices.shfqa.QAChannel": name 'Session' is not defined

This is probably due to type hinting.

if t.TYPE_HINTING:
    from zhinst.toolkit.session import Session

and using it in as type hint in, for example BaseInstrument:

def __init__(
      self,
      serial: str,
      device_type: str,
      session: "Session", <----
):

This could be probably be solved importing the whole zhinst.toolkit.session module

https://peps.python.org/pep-0484/

https://github.com/tox-dev/sphinx-autodoc-typehints#dealing-with-circular-imports

So it would result to:

from __future__ import annotations
import zhinst.toolkit.session

and using it in as type hint in, for example BaseInstrument:

def __init__(
      self,
      serial: str,
      device_type: str,
      session: zhinst.toolkit.session.Session
):

How to reproduce

Environment info

• Python version:
• zhinst-toolkit version:
• LabOne version:
• zhinst version:

Device/system information (if applicable)

Additional information

[jenshnielsen]

We gave up on using Sphinx-autodoc-typehints in QCoDeS for this exact reason

There is a long standing bug about this here
tox-dev/sphinx-autodoc-typehints#186

[markheik]

We gave up on using Sphinx-autodoc-typehints in QCoDeS for this exact reason

There is a long standing bug about this here tox-dev/sphinx-autodoc-typehints#186

@jenshnielsen Thanks for info, I did read the thread. I agree with you and will evaluate the changes required for this.

[markheik]

@jenshnielsen I did end to remove sphinx-autodoc-typehints and replace it with

autodoc_typehints = "both"
autodoc_typehints_format = "short"

I like autodoc_typehints="both" as it shows the type both in signature and description.