add missing files for mkdocs, fix newline error for flake8

Author: tipatterson-dev

.github/workflows/docs_pages.yaml

@@ -3,6 +3,10 @@ on: [ push, pull_request, workflow_dispatch ]
 permissions:
   contents: write
 
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: true
+
 jobs:
   build-docs:
     runs-on: ubuntu-latest
@@ -19,9 +23,9 @@ jobs:
       - name: Install dependencies
         run: uv sync --all-extras
 
-      - name: Sphinx build
+      - name: Build MkDocs site
         run: |
-          uv run sphinx-build -b html docs/source docs/build/html
+          uv run mkdocs build --strict
 
       - name: Deploy documentation
         uses: peaceiris/actions-gh-pages@v4

docs/markdown/api.md

@@ -0,0 +1,90 @@
+# API Reference
+
+All public symbols are re-exported from the top-level package and can be
+imported directly:
+
+```python
+from oshconnect import OSHConnect, Node, Datastream, TimePeriod, ObservationFormat
+```
+
+Lower-level CS API utilities are available from the `oshconnect.csapi4py`
+sub-package:
+
+```python
+from oshconnect.csapi4py import APIResourceTypes, MQTTCommClient, ConnectedSystemsRequestBuilder
+```
+
+---
+
+## Core Application
+
+::: oshconnect.oshconnectapi
+
+---
+
+## Streamable Resources
+
+The primary objects for interacting with systems, datastreams, and control
+streams on an OSH node. Includes `Node`, `System`, `Datastream`,
+`ControlStream`, and supporting enums.
+
+::: oshconnect.streamableresource
+
+---
+
+## Resource Data Models
+
+Pydantic models that represent CS API resources returned from or sent to an
+OSH server.
+
+::: oshconnect.resource_datamodels
+
+---
+
+## SWE Schema Components
+
+Builder classes for constructing datastream and command schemas using SWE
+Common data types.
+
+::: oshconnect.swe_components
+
+::: oshconnect.schema_datamodels
+
+---
+
+## Event System
+
+Pub/sub event bus for in-process notifications. Implement `IEventListener`
+to receive events.
+
+::: oshconnect.eventbus
+
+::: oshconnect.events.core
+
+::: oshconnect.events.builder
+
+---
+
+## Time Management
+
+::: oshconnect.timemanagement
+
+---
+
+## CS API Integration (`csapi4py`)
+
+### Constants and Enums
+
+::: oshconnect.csapi4py.constants
+
+### Request Builder
+
+::: oshconnect.csapi4py.con_sys_api
+
+### API Helper
+
+::: oshconnect.csapi4py.default_api_helpers
+
+### MQTT Client
+
+::: oshconnect.csapi4py.mqtt

docs/markdown/architecture.md

@@ -0,0 +1,93 @@
+# Architecture
+
+OSHConnect is structured around a small number of long-lived objects that mirror
+the resource hierarchy of the OGC API – Connected Systems specification.
+
+## Object hierarchy
+
+```mermaid
+graph TD
+    OSHConnect[OSHConnect<br/><i>application entry point</i>]
+    Node[Node<br/><i>connection to one OSH server</i>]
+    APIHelper[APIHelper<br/><i>CS API HTTP requests</i>]
+    Session[SessionManager<br/><i>OSHClientSession instances</i>]
+    MQTT[MQTTCommClient<br/><i>paho-mqtt wrapper</i>]
+    System[System<br/><i>sensor system</i>]
+    Datastream[Datastream<br/><i>output channel — observations</i>]
+    ControlStream[ControlStream<br/><i>input channel — commands &amp; status</i>]
+
+    OSHConnect --> Node
+    Node --> APIHelper
+    Node --> Session
+    Node --> MQTT
+    Node --> System
+    System --> Datastream
+    System --> ControlStream
+```
+
+## Key abstractions
+
+- **`OSHConnect`** (`oshconnectapi.py`) — top-level class. Owns nodes and
+  provides `discover_systems()`, `discover_datastreams()`,
+  `save_config()` / `load_config()`, and `create_and_insert_system()`.
+- **`Node`** (`streamableresource.py`) — wraps a server connection. Drives
+  discovery via `APIHelper` and owns the `MQTTCommClient`. All HTTP resource
+  creation goes through here.
+- **`StreamableResource`** (`streamableresource.py`) — abstract base for
+  `System`, `Datastream`, and `ControlStream`. Manages MQTT
+  subscriptions/publications, WebSocket connections, and the inbound /
+  outbound message deques. Connection modes: `PUSH`, `PULL`, `BIDIRECTIONAL`.
+- **`Datastream` / `ControlStream`** (`streamableresource.py`) — concrete
+  streamable resources. Datastreams publish observations; ControlStreams
+  publish commands and receive status updates. Both follow CS API Part 3
+  topic conventions (`:data`, `:status`, `:commands`).
+- **`resource_datamodels.py`** — Pydantic models for the CS API resource types
+  (`SystemResource`, `DatastreamResource`, `ControlStreamResource`,
+  `ObservationResource`). These map directly to API request and response
+  bodies.
+- **`swe_components.py`** — Pydantic models for SWE Common schema components
+  (`DataRecordSchema`, `QuantitySchema`, `VectorSchema`, etc.). Used to define
+  observation and command schemas when creating new datastreams.
+- **`csapi4py/`** — sub-package that handles the CS API specifics: URL
+  construction (`endpoints.py`), request building (`con_sys_api.py`), enums
+  (`constants.py`), and MQTT topic conventions (`mqtt.py`).
+- **`EventHandler`** (`eventbus.py`) — singleton pub/sub bus. Listeners
+  subscribe to event types (e.g. `NEW_OBSERVATION`) and topic strings; events
+  are dispatched asynchronously through an internal queue.
+- **`timemanagement.py`** — `TimeInstant` (epoch / ISO-8601), `TimePeriod`,
+  `TemporalModes` (`REAL_TIME`, `ARCHIVE`, `BATCH`), and `TimeUtils`
+  conversions.
+
+## Typical data flow
+
+```mermaid
+sequenceDiagram
+    autonumber
+    participant App as OSHConnect
+    participant N as Node
+    participant H as APIHelper
+    participant S as Server
+    participant DS as Datastream
+
+    App->>N: add_node()
+    App->>N: discover_systems()
+    N->>H: retrieve_resource(SYSTEM)
+    H->>S: HTTP GET /systems
+    S-->>H: JSON
+    H-->>N: System objects
+    App->>DS: discover_datastreams()
+    DS->>DS: initialize() — open MQTT/WebSocket
+    DS->>DS: start() — begin streaming
+    S-->>DS: observations → _inbound_deque
+    Note over App,DS: To insert: resource.insert_self() →<br/>APIHelper.create_resource() → POST →<br/>server returns Location header with new ID
+```
+
+## Dependencies
+
+- **pydantic** — all resource and schema models. Bumping the minimum requires
+  confirming pre-built wheels exist for all supported Python versions
+  (3.12 – 3.14).
+- **shapely** — geometry handling for spatial resources.
+- **paho-mqtt** — MQTT streaming for CS API Part 3.
+- **websockets** / **aiohttp** — WebSocket and async HTTP streaming.
+- **requests** — synchronous HTTP for discovery and resource creation.

docs/markdown/index.md

@@ -0,0 +1,24 @@
+# OSHConnect-Python
+
+OSHConnect-Python is the Python member of the OSHConnect family of application
+libraries. It provides a simple, straightforward way to interact with
+OpenSensorHub (or any other OGC API – Connected Systems server).
+
+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 using 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`.
+
+## Where to next
+
+- [Architecture](architecture.md) — object hierarchy, data flow, and key abstractions
+- [Tutorial](tutorial.md) — common workflows for connecting, discovering, streaming, and inserting resources
+- [API Reference](api.md) — auto-generated reference for every public symbol