Hide private submodules from documentation

[bkeryan]

Tech Debt

The documentation configuration currently uses autoapi-skip-member to prevent sphinx-autoapi from documenting class definitions in private submodules:

def skip_aliases(app, what, name, obj, skip, options):
    """Skip documentation for classes that are exported from multiple modules."""
    # For names that are defined in a private sub-module and aliased into a
    # public package, hide the definition.
    if name.startswith("nitypes.time._") or name.startswith("nitypes.waveform._"):
        skip = True

    return skip


def setup(sphinx):
    """Sphinx setup callback."""
    sphinx.connect("autoapi-skip-member", skip_aliases)

It would be better to use :canonical:, but I don't know how to do this without support from sphinx-autoapi upstream.

Upstream issue: readthedocs/sphinx-autoapi#411

AB#3112717

[bkeryan]

Importing the public aliases causes sphinx-autoapi to use the public aliases in the docs:

diff --git a/src/nitypes/waveform/_analog.py b/src/nitypes/waveform/_analog.py
index f932d00..365efdb 100644
--- a/src/nitypes/waveform/_analog.py
+++ b/src/nitypes/waveform/_analog.py
@@ -8,10 +8,9 @@ import numpy.typing as npt
 from typing_extensions import TypeVar, final, override
 
 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 import ExtendedPropertyValue, NumericWaveform, ScaleMode, Timing
+from nitypes.waveform._numeric import _TOtherScaled
+from nitypes.waveform._timing import _AnyDateTime, _AnyTimeDelta
 
 # _TRaw specifies the type of the raw_data array. AnalogWaveform accepts a narrower set of types
 # than NumericWaveform.

However, it causes circular imports.

ERROR src/nitypes/scalar/__init__.py - ImportError: cannot import name 'ExtendedPropertyValue' from partially initialized module 'nitypes.waveform' (most likely due to a circular import) (/Users/bkeryan/src/work/nitypes-python/src/nitypes/waveform/__init__.py)

Working around it with

if TYPE_CHECKING:
    from nitypes.waveform import ExtendedPropertyValue

only works for type hints, not base classes like NumericWaveform.

[bkeryan]

This seems to work:

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

[bkeryan]

Current status:

• Imports of public classes are using the technique described in Hide private submodules from documentation #16 (comment) .
• Imports of TypeVars and TypeAliases are not.

Example: https://nitypes.readthedocs.io/en/latest/autoapi/nitypes/waveform/AnalogWaveform.html#AnalogWaveform.from_array_1d

classmethod from_array_1d(array: numpy.typing.NDArray[_TOtherRaw], dtype: None = ..., *, copy: bool = ..., start_index: SupportsIndex | None = ..., sample_count: SupportsIndex | None = ..., extended_properties: collections.abc.Mapping[str, nitypes.waveform.ExtendedPropertyValue] | None = ..., timing: nitypes.waveform.Timing[nitypes.waveform._timing._AnyDateTime, nitypes.waveform._timing._AnyTimeDelta, nitypes.waveform._timing._AnyTimeDelta] | None = ..., scale_mode: nitypes.waveform.ScaleMode | None = ...)→ AnalogWaveform[_TOtherRaw]

nitypes.waveform.ExtendedPropertyValue, nitypes.waveform.Timing, and nitypes.waveform.ScaleMode are the public exports.

nitypes.waveform._timing._AnyDateTime and nitypes.waveform._timing._AnyTimeDelta are TypeAliases in a private submodule.

_TOtherRaw is a TypeVar in a private submodule. Sphinx-autoapi is not displaying its submodule name here, but I think there may be some situations where it does.

After discussion with @mshafer-NI, I think it makes sense to do the following:

• Make TypeAliases (e.g. _AnyTimeDelta) public or replace them with the corresponding unions (e.g. bt.TimeDelta | dt.timedelta | ht.timedelta)
• Make TypeVars (e.g. _TOtherRaw) public
  • Challenge: some of the waveforms use the same TypeVar name with different bounds. These may need to live in separate submodules or be renamed.

In a few years, Python 3.11 will go EOL. At that point, we can replace the TypeVars with PEP 695 generic syntax. However, we do not necessarily need to break compatibility with code that imports our exported TypeVars. We can keep exporting them as long as we want, and we can also implement a module-level __getattr__ that emits DeprecationWarning if they are imported.