docs: Use public package/module names more consistently and show type hints in signatures (#153)

* docs: Rework imports to hide private submodules

* docs: Show type hints in signatures

Author: bkeryan

docs/conf.py

@@ -49,7 +49,7 @@
 autoapi_dirs = [root_path / "src" / "nitypes"]
 autoapi_own_page_level = "class"
 autoapi_type = "python"
-autodoc_typehints = "description"
+autodoc_typehints = "both"
 # Uncomment for debugging
 # autoapi_keep_files = True
 

src/nitypes/bintime/_datetime.py

@@ -2,19 +2,33 @@
 
 import datetime as dt
 from functools import singledispatchmethod
-from typing import Any, ClassVar, SupportsIndex, Union, cast, final, overload
+from typing import (
+    TYPE_CHECKING,
+    Any,
+    ClassVar,
+    SupportsIndex,
+    Union,
+    cast,
+    final,
+    overload,
+)
 
 import hightime as ht
 from typing_extensions import Self, TypeAlias
 
 from nitypes._exceptions import invalid_arg_type, invalid_arg_value
-from nitypes.bintime._time_value_tuple import TimeValueTuple
 from nitypes.bintime._timedelta import (
     _OTHER_TIMEDELTA_TUPLE,
-    TimeDelta,
     _OtherTimeDelta,
 )
 
+if TYPE_CHECKING:
+    # Import from the public package so the docs don't reference private submodules.
+    from nitypes.bintime import TimeDelta, TimeValueTuple
+else:
+    from nitypes.bintime._time_value_tuple import TimeValueTuple
+    from nitypes.bintime._timedelta import TimeDelta
+
 _DT_EPOCH_1904 = dt.datetime(1904, 1, 1, tzinfo=dt.timezone.utc)
 _HT_EPOCH_1904 = ht.datetime(1904, 1, 1, tzinfo=dt.timezone.utc)
 

src/nitypes/bintime/_timedelta.py

@@ -6,14 +6,20 @@
 import operator
 from decimal import Decimal
 from functools import singledispatchmethod
-from typing import Any, ClassVar, SupportsIndex, Union, final, overload
+from typing import TYPE_CHECKING, Any, ClassVar, SupportsIndex, Union, final, overload
 
 import hightime as ht
 from typing_extensions import Self, TypeAlias
 
 from nitypes._arguments import arg_to_int
 from nitypes._exceptions import int_out_of_range, invalid_arg_type
-from nitypes.bintime._time_value_tuple import TimeValueTuple
+
+if TYPE_CHECKING:
+    # Import from the public package so the docs don't reference private submodules.
+    from nitypes.bintime import TimeValueTuple
+else:
+    from nitypes.bintime._time_value_tuple import TimeValueTuple
+
 
 _INT64_MAX = (1 << 63) - 1
 _INT64_MIN = -(1 << 63)

src/nitypes/waveform/_analog.py

@@ -5,13 +5,21 @@
 
 import numpy as np
 import numpy.typing as npt
-from typing_extensions import TypeVar, final, override
+from typing_extensions import TypeVar, final, override, TYPE_CHECKING
 
 from nitypes._numpy import long as _np_long, ulong as _np_ulong
-from nitypes.waveform._extended_properties import ExtendedPropertyValue
-from nitypes.waveform._numeric import NumericWaveform, _TOtherScaled
-from nitypes.waveform._scaling import ScaleMode
-from nitypes.waveform._timing import Timing, _AnyDateTime, _AnyTimeDelta
+from nitypes.waveform._numeric import _TOtherScaled
+from nitypes.waveform._timing import _AnyDateTime, _AnyTimeDelta
+
+if TYPE_CHECKING:
+    # Import from the public package so the docs don't reference private submodules.
+    from nitypes.waveform import ExtendedPropertyValue, NumericWaveform, ScaleMode, Timing
+else:
+    from nitypes.waveform._extended_properties import ExtendedPropertyValue
+    from nitypes.waveform._numeric import NumericWaveform
+    from nitypes.waveform._scaling import ScaleMode
+    from nitypes.waveform._timing import Timing
+
 
 # _TRaw specifies the type of the raw_data array. AnalogWaveform accepts a narrower set of types
 # than NumericWaveform.

src/nitypes/waveform/_complex.py

@@ -5,13 +5,25 @@
 
 import numpy as np
 import numpy.typing as npt
-from typing_extensions import TypeVar, final, override
+from typing_extensions import TYPE_CHECKING, TypeVar, final, override
 
 from nitypes.complex import ComplexInt32Base, ComplexInt32DType, convert_complex
-from nitypes.waveform._extended_properties import ExtendedPropertyValue
-from nitypes.waveform._numeric import NumericWaveform, _TOtherScaled
-from nitypes.waveform._scaling import ScaleMode
-from nitypes.waveform._timing import Timing, _AnyDateTime, _AnyTimeDelta
+from nitypes.waveform._numeric import _TOtherScaled
+from nitypes.waveform._timing import _AnyDateTime, _AnyTimeDelta
+
+if TYPE_CHECKING:
+    # Import from the public package so the docs don't reference private submodules.
+    from nitypes.waveform import (
+        ExtendedPropertyValue,
+        NumericWaveform,
+        ScaleMode,
+        Timing,
+    )
+else:
+    from nitypes.waveform._extended_properties import ExtendedPropertyValue
+    from nitypes.waveform._numeric import NumericWaveform
+    from nitypes.waveform._scaling import ScaleMode
+    from nitypes.waveform._timing import Timing
 
 # _TRaw specifies the type of the raw_data array. ComplexWaveform accepts a narrower set of types
 # than NumericWaveform. Note that ComplexInt32Base is an alias for np.void, but other structured

src/nitypes/waveform/_digital/_signal.py

@@ -9,7 +9,11 @@
 from nitypes.waveform._digital._types import _TState
 
 if TYPE_CHECKING:
-    from nitypes.waveform._digital._waveform import DigitalWaveform  # circular import
+    # Import from the public package so the docs don't reference private submodules.
+    from nitypes.waveform import DigitalWaveform
+else:
+    # DigitalWaveform is a circular import.
+    pass
 
 
 class DigitalWaveformSignal(Generic[_TState]):

src/nitypes/waveform/_digital/_signal_collection.py

@@ -4,11 +4,14 @@
 from typing import TYPE_CHECKING, Generic, overload
 
 from nitypes._exceptions import invalid_arg_type
-from nitypes.waveform._digital._signal import DigitalWaveformSignal
 from nitypes.waveform._digital._types import _TState
 
 if TYPE_CHECKING:
-    from nitypes.waveform._digital._waveform import DigitalWaveform  # circular import
+    # Import from the public package so the docs don't reference private submodules.
+    from nitypes.waveform import DigitalWaveform, DigitalWaveformSignal
+else:
+    # DigitalWaveform is a circular import.
+    from nitypes.waveform._digital._signal import DigitalWaveformSignal
 
 
 class DigitalWaveformSignalCollection(Generic[_TState], Sequence[DigitalWaveformSignal[_TState]]):

src/nitypes/waveform/_digital/_waveform.py

@@ -4,7 +4,7 @@
 import sys
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
-from typing import Any, Generic, SupportsIndex, overload
+from typing import TYPE_CHECKING, Any, Generic, SupportsIndex, overload
 
 import hightime as ht
 import numpy as np
@@ -15,8 +15,6 @@
 from nitypes._exceptions import invalid_arg_type, invalid_array_ndim
 from nitypes._numpy import asarray as _np_asarray
 from nitypes.waveform._digital._port import bit_mask, get_port_dtype, port_to_line_data
-from nitypes.waveform._digital._signal_collection import DigitalWaveformSignalCollection
-from nitypes.waveform._digital._state import DigitalState
 from nitypes.waveform._digital._types import (
     _DIGITAL_PORT_DTYPES,
     _DIGITAL_STATE_DTYPES,
@@ -35,14 +33,32 @@
 from nitypes.waveform._extended_properties import (
     CHANNEL_NAME,
     LINE_NAMES,
-    ExtendedPropertyDictionary,
-    ExtendedPropertyValue,
 )
-from nitypes.waveform._timing import Timing, _AnyDateTime, _AnyTimeDelta
+from nitypes.waveform._timing import _AnyDateTime, _AnyTimeDelta
 
 if sys.version_info < (3, 10):
     import array as std_array
 
+if TYPE_CHECKING:
+    # Import from the public package so the docs don't reference private submodules.
+    from nitypes.waveform import (
+        DigitalState,
+        DigitalWaveformSignalCollection,
+        ExtendedPropertyDictionary,
+        ExtendedPropertyValue,
+        Timing,
+    )
+else:
+    from nitypes.waveform._digital._signal_collection import (
+        DigitalWaveformSignalCollection,
+    )
+    from nitypes.waveform._digital._state import DigitalState
+    from nitypes.waveform._extended_properties import (
+        ExtendedPropertyDictionary,
+        ExtendedPropertyValue,
+    )
+    from nitypes.waveform._timing import Timing
+
 
 @dataclass(frozen=True)
 class DigitalWaveformFailure:

src/nitypes/waveform/_numeric.py

@@ -5,7 +5,7 @@
 import warnings
 from abc import ABC, abstractmethod
 from collections.abc import Mapping, Sequence
-from typing import Any, Generic, SupportsIndex, overload
+from typing import TYPE_CHECKING, Any, Generic, SupportsIndex, overload
 
 import hightime as ht
 import numpy as np
@@ -23,19 +23,30 @@
     create_start_index_or_sample_count_too_large_error,
     create_start_index_too_large_error,
 )
-from nitypes.waveform._extended_properties import (
-    CHANNEL_NAME,
-    UNIT_DESCRIPTION,
-    ExtendedPropertyDictionary,
-    ExtendedPropertyValue,
-)
-from nitypes.waveform._scaling import NO_SCALING, ScaleMode
-from nitypes.waveform._timing import Timing, _AnyDateTime, _AnyTimeDelta
+from nitypes.waveform._extended_properties import CHANNEL_NAME, UNIT_DESCRIPTION
+from nitypes.waveform._timing import _AnyDateTime, _AnyTimeDelta
 from nitypes.waveform._warnings import scale_mode_mismatch
 
 if sys.version_info < (3, 10):
     import array as std_array
 
+if TYPE_CHECKING:
+    # Import from the public package so the docs don't reference private submodules.
+    from nitypes.waveform import (
+        NO_SCALING,
+        ExtendedPropertyDictionary,
+        ExtendedPropertyValue,
+        ScaleMode,
+        Timing,
+    )
+else:
+    from nitypes.waveform._extended_properties import (
+        ExtendedPropertyDictionary,
+        ExtendedPropertyValue,
+    )
+    from nitypes.waveform._scaling import NO_SCALING, ScaleMode
+    from nitypes.waveform._timing import Timing
+
 # _TRaw specifies the type of the raw_data array. It is not limited to supported types. Requesting
 # an unsupported type raises TypeError at run time. It is invariant because waveforms are mutable.
 _TRaw = TypeVar("_TRaw", bound=np.generic)

src/nitypes/waveform/_scaling/_linear.py

@@ -1,11 +1,17 @@
 from __future__ import annotations
 
-from typing import SupportsFloat
+from typing import TYPE_CHECKING, SupportsFloat
 
 import numpy.typing as npt
 
 from nitypes._arguments import arg_to_float
-from nitypes.waveform._scaling._base import ScaleMode, _ScalarType
+from nitypes.waveform._scaling._base import _ScalarType
+
+if TYPE_CHECKING:
+    # Import from the public package so the docs don't reference private submodules.
+    from nitypes.waveform import ScaleMode
+else:
+    from nitypes.waveform._scaling._base import ScaleMode
 
 
 class LinearScaleMode(ScaleMode):