docs: consolidate doc trees into mkdocs site, remove stale sdk/docs (#140)

The SDK shipped two divergent doc trees: the published mkdocs site
(docs/) and a pdoc-era tree (sdk/docs/) that had drifted out of sync,
including a set_many() example that passed a dict instead of a list of
FieldUpdate objects. Both READMEs linked to the stale tree.

Pick docs/ (mkdocs) as the single canonical tree:

- Migrate the async usage guide into docs/guide/async.md, fixing the
  stale set_many() dict example to use FieldUpdate and updating cross
  links to match the mkdocs nav structure. (The configuration/error
  handling content in sdk/docs/ was superseded by the more accurate
  guide/connect.md, which already documents check_version,
  RESOURCE_EXHAUSTED retries, and TimeoutError, so it was dropped
  rather than migrated.)
- Add the new guide to mkdocs.yml's nav and cross-link it from
  docs/index.md and docs/guide/watch.md.
- Remove sdk/docs/ entirely, along with the pdoc wiring that generated
  its stale sdk/docs/api/*.html (Makefile `docs` target, the pdoc
  dependency in build/Dockerfile.tools and sdk/pyproject.toml, and the
  matching .gitignore entry). The Makefile `docs` target now builds the
  mkdocs site directly, matching what .github/workflows/docs.yml does.
- Repoint README.md and sdk/README.md documentation links at the
  published docs site (opendecree.github.io/decree-python) instead of
  the removed sdk/docs/ tree, and update CLAUDE.md's tooling table.

Closes #135

Author: zeevdr

.gitignore

@@ -34,7 +34,7 @@ htmlcov/
 .ruff_cache/
 
 # Generated docs
-sdk/docs/api/
+site/
 
 # OS
 .DS_Store

CLAUDE.md

@@ -16,7 +16,7 @@ clients, a field-watching subscription layer, and optional OpenTelemetry instrum
 | Lint / format | ruff |
 | Type checking | mypy |
 | Tests | pytest, pytest-asyncio |
-| Docs | pdoc |
+| Docs | mkdocs (material) + mkdocstrings |
 
 ## Development
 

Makefile

@@ -64,11 +64,11 @@ integration: $(TOOLS_SENTINEL)
 	@test -n "$(DECREE_TEST_ADDR)" || (echo "Set DECREE_TEST_ADDR=host:port" && exit 1)
 	$(DOCKER_RUN_ROOT) sh -c "cd sdk && pip install -e . -q 2>/dev/null && DECREE_TEST_ADDR=$(DECREE_TEST_ADDR) pytest -m integration -v"
 
-## docs: Generate API reference HTML from docstrings (pdoc)
-docs: $(TOOLS_SENTINEL)
-	@mkdir -p sdk/docs/api
-	$(DOCKER_RUN_ROOT) sh -c "cd sdk && pip install -e . -q 2>/dev/null && pdoc --output-directory /workspace/sdk/docs/api --no-show-source --docformat google opendecree !opendecree._generated && chown -R $(shell id -u):$(shell id -g) /workspace/sdk/docs/api"
-	@echo "Generated API docs in sdk/docs/api/"
+## docs: Build the mkdocs documentation site (output in site/)
+docs:
+	pip install -q 'mkdocs-material' 'mkdocstrings[python]'
+	mkdocs build
+	@echo "Built docs site in site/"
 
 ## build: Build sdist + wheel
 build: $(TOOLS_SENTINEL)

README.md

@@ -54,7 +54,7 @@ with ConfigClient("localhost:9090", subject="myapp") as client:
 ```
 
 > **Fork safety:** gRPC channels are not fork-safe. Create `ConfigClient` (and start any watcher)
-> *after* forking — not before. See [Fork safety](sdk/docs/watching.md#fork-safety) for details.
+> *after* forking — not before. See [Fork safety](https://opendecree.github.io/decree-python/guide/watch/#fork-safety) for details.
 
 ## Async
 
@@ -80,10 +80,13 @@ Runnable examples in the [`examples/`](examples/) directory:
 
 ## Documentation
 
-- [Quick Start](sdk/docs/quickstart.md)
-- [Configuration](sdk/docs/configuration.md)
-- [Watching](sdk/docs/watching.md)
-- [Async Usage](sdk/docs/async.md)
+Full documentation, including guides and the API reference, is published at
+**[opendecree.github.io/decree-python](https://opendecree.github.io/decree-python)**:
+
+- [Connecting](https://opendecree.github.io/decree-python/guide/connect/) — client options (auth, TLS, retry, timeouts, error handling)
+- [Watching](https://opendecree.github.io/decree-python/guide/watch/) — live subscriptions and change patterns
+- [Async Usage](https://opendecree.github.io/decree-python/guide/async/) — async client and watcher
+- [API Reference](https://opendecree.github.io/decree-python/api/) — full auto-generated API docs
 
 For detailed concepts (schemas, typed values, versioning, auth), see the [main OpenDecree docs](https://github.com/opendecree/decree).
 

build/Dockerfile.tools

@@ -11,7 +11,6 @@ RUN pip install --no-cache-dir \
     grpcio>=1.68.0 \
     protobuf>=5.29.0 \
     googleapis-common-protos>=1.66.0 \
-    build \
-    pdoc>=15.0
+    build
 
 WORKDIR /workspace

sdk/docs/async.md docs/guide/async.mdsdk/docs/async.md renamed to docs/guide/async.md

@@ -5,7 +5,7 @@ The SDK provides async equivalents for all sync APIs, built on `grpc.aio`.
 ## AsyncConfigClient
 
 ```python
-from opendecree import AsyncConfigClient
+from opendecree import AsyncConfigClient, FieldUpdate
 
 async with AsyncConfigClient("localhost:9090", subject="myapp") as client:
     # Typed gets (same overload pattern as sync)
@@ -18,23 +18,26 @@ async with AsyncConfigClient("localhost:9090", subject="myapp") as client:
 
     # Writes
     await client.set("tenant-id", "payments.fee", "0.5%")
-    await client.set_many("tenant-id", {"a": "1", "b": "2"})
+    await client.set_many(
+        "tenant-id",
+        [FieldUpdate("a", "1"), FieldUpdate("b", "2")],
+        description="batch update",
+    )
     await client.set_null("tenant-id", "payments.fee")
 ```
 
-Same constructor options as `ConfigClient` — see [Configuration](configuration.md).
+Same constructor options as `ConfigClient` — see [Connecting](connect.md).
 
 ## AsyncConfigWatcher
 
 ```python
 from opendecree import AsyncConfigClient
 
 async with AsyncConfigClient("localhost:9090", subject="myapp") as client:
-    watcher = client.watch("tenant-id")
-    fee = watcher.field("payments.fee", float, default=0.01)
-    enabled = watcher.field("payments.enabled", bool, default=False)
+    async with client.watch("tenant-id") as watcher:
+        fee = watcher.field("payments.fee", float, default=0.01)
+        enabled = watcher.field("payments.enabled", bool, default=False)
 
-    async with watcher:
         # .value works the same
         print(fee.value)
 
@@ -48,12 +51,12 @@ async with AsyncConfigClient("localhost:9090", subject="myapp") as client:
 Use `async for` instead of `for`:
 
 ```python
-watcher = client.watch("tenant-id")
-fee = watcher.field("payments.fee", float, default=0.01)
+async with AsyncConfigClient("localhost:9090", subject="myapp") as client:
+    async with client.watch("tenant-id") as watcher:
+        fee = watcher.field("payments.fee", float, default=0.01)
 
-async with watcher:
-    async for change in fee.changes():
-        print(f"{change.old_value} -> {change.new_value}")
+        async for change in fee.changes():
+            print(f"{change.old_value} -> {change.new_value}")
 ```
 
 ### Callbacks
@@ -83,11 +86,18 @@ The public API is otherwise identical — same constructor options, same `get()`
 ## When to use async
 
 Use the async API when:
+
 - Your application already uses asyncio (FastAPI, aiohttp, etc.)
 - You need to manage many concurrent connections efficiently
 
 Use the sync API when:
+
 - Your application is synchronous (Flask, Django, scripts)
 - Simplicity matters more than concurrency
 
 Both APIs are equally capable and tested.
+
+## Next steps
+
+- [Connecting](connect.md) — client options (auth, TLS, retry, error handling)
+- [Watching](watch.md) — live subscriptions and change patterns

docs/guide/watch.md

@@ -130,6 +130,8 @@ async with AsyncConfigClient("localhost:9090", subject="myapp") as client:
 
 Callbacks work the same as the sync watcher — they are plain functions, not coroutines.
 
+See [Async Usage](async.md) for the full async client and watcher API.
+
 ## Fork safety
 
 gRPC channels are **not fork-safe**. Do not create a `ConfigClient` before calling `os.fork()`.

docs/index.md

@@ -82,6 +82,7 @@ Runnable examples are available in the [`examples/`](https://github.com/opendecr
 
 - [Connecting](guide/connect.md) — all client options (auth, TLS, retry, timeouts)
 - [Watching](guide/watch.md) — live subscriptions and change patterns
+- [Async Usage](guide/async.md) — async client and watcher
 - [API Reference](api/index.md) — full auto-generated API docs
 
 For server concepts (schemas, typed values, versioning, auth), see the [main OpenDecree docs](https://github.com/opendecree/decree).

mkdocs.yml

@@ -46,6 +46,7 @@ nav:
   - Guide:
     - Connecting: guide/connect.md
     - Watching: guide/watch.md
+    - Async Usage: guide/async.md
   - API Reference: api/index.md
 
 markdown_extensions:

sdk/README.md

@@ -61,10 +61,13 @@ async with AsyncConfigClient("localhost:9090", subject="myapp") as client:
 
 ## Documentation
 
-- [Quick Start](docs/quickstart.md)
-- [Configuration](docs/configuration.md)
-- [Watching](docs/watching.md)
-- [Async Usage](docs/async.md)
+Full documentation, including guides and the API reference, is published at
+**[opendecree.github.io/decree-python](https://opendecree.github.io/decree-python)**:
+
+- [Connecting](https://opendecree.github.io/decree-python/guide/connect/) — client options (auth, TLS, retry, timeouts, error handling)
+- [Watching](https://opendecree.github.io/decree-python/guide/watch/) — live subscriptions and change patterns
+- [Async Usage](https://opendecree.github.io/decree-python/guide/async/) — async client and watcher
+- [API Reference](https://opendecree.github.io/decree-python/api/) — full auto-generated API docs
 
 For detailed concepts (schemas, typed values, versioning, auth), see the [main OpenDecree docs](https://github.com/opendecree/decree).