docs: some documentation/thoughts on properly implementing overlay packages

doc/overlays/overlay/setup.py

@@ -0,0 +1,17 @@
+from setuptools import setup, find_namespace_packages # type: ignore
+
+
+def main() -> None:
+    pkgs = find_namespace_packages('src')
+    pkg = min(pkgs)
+    setup(
+        name='hpi-overlay',
+        zip_safe=False,
+        packages=pkgs,
+        package_dir={'': 'src'},
+        package_data={pkg: ['py.typed']},
+    )
+
+
+if __name__ == '__main__':
+    main()

doc/overlays/overlay/src/my/twitter/all.py

@@ -0,0 +1,8 @@
+print(f'[overlay] {__name__} hello')
+
+from .common import merge
+
+def tweets() -> list[str]:
+    from . import gdpr
+    from . import talon
+    return merge(gdpr, talon)

doc/overlays/overlay/src/my/twitter/talon.py

@@ -0,0 +1,9 @@
+print(f'[overlay] {__name__} hello')
+
+def tweets() -> list[str]:
+    return [
+        'talon tweet 1',
+        'talon tweet 2',
+    ]
+
+trigger_mypy_error: str = 123