Implement CS API Part 3 pub/sub topics, expand public API surface, and update docs

  - Add :data suffix to all MQTT resource data topics per CS API Part 3 draft spec
    (observations:data, commands:data, status:data)
  - Add get_event_topic() and subscribe_events() to StreamableResource for CloudEvents lifecycle notification subscriptions
  - Add data_topic flag to APIHelper.get_mqtt_topic() and StreamableResource.get_mqtt_topic()
  - Expand __init__.py to re-export 36 public symbols across core resources, timemanagement, resource data models, SWE schema components, event system, and CS API constants — enabling single-import workflows
  - Populate csapi4py/__init__.py with re-exports for lower-level access
  - Fix pre-existing bare import bug: `from eventbus` → `from .eventbus` in oshconnectapi.py
  - Bump version to 0.4.0a0
  - Add tests/test_imports.py to verify all public symbols are importable without src-path hacks (works on any machine after uv sync / pip install -e .)
  - Overhaul docs: fix stale module references in api.rst, update tutorial import paths, add Part 3 streaming and event subscription examples, fix conf.py sys.path, update README with doc generation instructions

Author: tipatterson-dev

README.md

@@ -5,6 +5,30 @@ recommendations for data, retrieving data in real time, archival streams, and ba
 
 API Documentation available [here](https://botts-innovative-research.github.io/OSHConnect-Python/)
 
-Links:  
+Links:
  * [Architecture Doc](https://docs.google.com/document/d/1pIaeQw0ocU6ApNgqTVRZuSwjJAbhCcmweMq6RiVYEic/edit?usp=sharing)
- * [UML Diagram](https://drive.google.com/file/d/1FVrnYiuAR8ykqfOUa1NuoMyZ1abXzMPw/view?usp=drive_link)
+ * [UML Diagram](https://drive.google.com/file/d/1FVrnYiuAR8ykqfOUa1NuoMyZ1abXzMPw/view?usp=drive_link)
+
+## Generating the Docs
+
+The documentation is built with [Sphinx](https://www.sphinx-doc.org/). Dev dependencies (including Sphinx) are installed automatically with:
+
+```bash
+uv sync
+```
+
+Then build the HTML docs:
+
+```bash
+uv run sphinx-build -b html docs/source docs/build/html
+```
+
+The output will be in `docs/build/html/`. Open `docs/build/html/index.html` in a browser to view locally.
+
+To do a clean rebuild:
+
+```bash
+uv run sphinx-build -E -b html docs/source docs/build/html
+```
+
+The `-E` flag forces Sphinx to re-read all source files rather than using cached data.

docs/source/api.rst

@@ -1,69 +1,117 @@
 API Reference
 =============
 
-OSHConnect
-----------
+All public symbols are re-exported from the top-level package and can be imported directly::
 
+    from oshconnect import OSHConnect, Node, Datastream, TimePeriod, ObservationFormat, ...
+
+Lower-level CS API utilities are available from the ``oshconnect.csapi4py`` subpackage::
+
+    from oshconnect.csapi4py import APIResourceTypes, MQTTCommClient, ConnectedSystemsRequestBuilder, ...
+
+---
+
+Core Application
+----------------
 
-OSHConnect Utilities and Helpers
---------------------------------
 .. automodule:: oshconnect.oshconnectapi
     :members:
     :undoc-members:
     :show-inheritance:
 
-OSH Connect Data Models
------------------------
-These are the second highest level pieces in the hierarchy of the library and the utilities needed to help almost
-everything else in the app function.
+---
+
+Streamable Resources
+--------------------
+These are the primary objects for interacting with systems, datastreams, and control streams on an OSH node.
+Includes ``Node``, ``System``, ``Datastream``, ``ControlStream``, and supporting enums.
+
+.. automodule:: oshconnect.streamableresource
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+---
+
+Resource Data Models
+--------------------
+Pydantic models that represent CS API resources returned from or sent to an OSH server.
 
-.. automodule:: oshconnect.osh_connect_datamodels
+.. automodule:: oshconnect.resource_datamodels
     :members:
     :undoc-members:
     :show-inheritance:
 
+---
 
-DataSources and Messaging
--------------------------
-Due to their extreme importance in the library, the data sources are listed separately along with the classes that help
-manage them and their data.
+SWE Schema Components
+---------------------
+Builder classes for constructing datastream and command schemas using SWE Common data types.
 
-.. automodule:: oshconnect.datasource
+.. automodule:: oshconnect.swe_components
     :members:
     :undoc-members:
     :show-inheritance:
 
+.. automodule:: oshconnect.schema_datamodels
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+---
+
+Event System
+------------
+Pub/sub event bus for in-process notifications. Implement ``IEventListener`` to receive events.
+
+.. automodule:: oshconnect.eventbus
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+---
+
 Time Management
 ---------------
-Currently **WIP** but this module will contain the classes and functions that help manage the current time and other
-playback features of groups of datasources/datafeeds
 
 .. automodule:: oshconnect.timemanagement
     :members:
     :undoc-members:
     :show-inheritance:
 
-Styling
--------
-**WIP** This module contains the classes and functions that help manage the styling and visualization recommendations that
-the library provides.
+---
 
-Datastore
----------
-**WIP** This module is for managing the state of the app. The configurations files are intended to be interchgangale
-among all language versions of the OSHConnect ecosystem.
+CS API Integration (``csapi4py``)
+----------------------------------
 
-Core Data Models
-----------------
-Theses data models are not often intended to be used directly by the user, but are used by the library to help manage
-validation of data that flows to and from the API.
+Constants and Enums
+~~~~~~~~~~~~~~~~~~~
 
-.. automodule:: oshconnect.core_datamodels
+.. automodule:: oshconnect.csapi4py.constants
     :members:
     :undoc-members:
     :show-inheritance:
 
+Request Builder
+~~~~~~~~~~~~~~~
 
+.. automodule:: oshconnect.csapi4py.con_sys_api
+    :members:
+    :undoc-members:
+    :show-inheritance:
 
-Helpers
-~~~~~~~
+API Helper
+~~~~~~~~~~
+
+.. automodule:: oshconnect.csapi4py.default_api_helpers
+    :members:
+    :undoc-members:
+    :show-inheritance:
+
+MQTT Client
+~~~~~~~~~~~
+
+.. automodule:: oshconnect.csapi4py.mqtt
+    :members:
+    :undoc-members:
+    :show-inheritance:

docs/source/conf.py

@@ -10,7 +10,7 @@
 import sys
 import traceback
 
-sys.path.insert(0, os.path.abspath("../.."))
+sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), '../../src')))
 
 
 def process_exception(app, what, name, obj, options, lines):
@@ -22,9 +22,9 @@ def setup(app):
 
 
 project = 'OSHConnect-Python'
-copyright = '2024, Botts Innovative Research, Inc.'
+copyright = '2025, Botts Innovative Research, Inc.'
 author = 'Ian Patterson'
-release = '0.2'
+release = '0.4'
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration

docs/source/index.rst

@@ -3,17 +3,28 @@ Welcome to OSHConnect-Python's documentation!
 
 OSHConnect-Python
 =================
-OSHConnect-Python is the Python version of the OSHConnect family of application libraries inteded to provide a simple
-and straightforward way to interact with OpenSensorHub (or another CSAPI server) by way of OGC API - Connected Systems.
-It supports or will support at the time of a 1.0 release Part 1 and Part 2 of the Connected Systems api, as well as
-certain streaming features made possible by OpenSensorHub.
+OSHConnect-Python is the Python version of the OSHConnect family of application libraries intended to provide a
+simple and straightforward way to interact with OpenSensorHub (or another CS API server) by way of
+OGC API - Connected Systems.
+
+It supports Parts 1, 2, and 3 (Pub/Sub) of the OGC Connected Systems API, including:
+
+- System, Datastream, and ControlStream discovery and management
+- Real-time MQTT streaming with CS API Part 3 ``:data`` topic conventions
+- Resource event topic subscriptions (CloudEvents lifecycle notifications)
+- Batch retrieval and archival stream playback
+- Configuration persistence (JSON save/load)
+- SWE Common schema builders for defining datastream and command schemas
+
+All major classes and utilities are importable directly from ``oshconnect``.
+Lower-level CS API utilities are available from ``oshconnect.csapi4py``.
 
 .. toctree::
    :maxdepth: 2
    :caption: Contents
 
-   api
    tutorial
+   api
 
 
 
@@ -22,6 +33,4 @@ Indices and tables
 
 * :ref:`genindex`
 * :ref:`modindex`
-* :ref:`search`
-
-
+* :ref:`search`