Improve developer documentation

.github/workflows/docs.yml

@@ -0,0 +1,37 @@
+name: docs
+
+on:
+  push:
+    branches:
+      - main
+      - v2/docs
+
+permissions:
+  contents: write
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v3
+
+      - name: Install docs dependencies
+        run: uv pip install -e ".[docs]"
+
+      - name: Build site
+        run: uv run mkdocs build
+
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: site

docs/api-reference.md

@@ -0,0 +1,13 @@
+::: pyoverkiz.client.OverkizClient
+
+::: pyoverkiz.models
+    options:
+      show_source: false
+
+::: pyoverkiz.enums
+    options:
+      show_source: false
+
+::: pyoverkiz.exceptions
+    options:
+      show_source: false

docs/authentication.md

@@ -0,0 +1,64 @@
+# Authentication
+
+## Cloud username and password
+
+Cloud authentication uses a vendor server from `Server` plus `UsernamePasswordCredentials`.
+
+```python
+import asyncio
+
+from pyoverkiz.auth.credentials import UsernamePasswordCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.enums import Server
+
+
+async def main() -> None:
+    async with OverkizClient(
+        server=Server.SOMFY_EUROPE,
+        credentials=UsernamePasswordCredentials("[email protected]", "password"),
+    ) as client:
+        await client.login()
+        print(await client.get_api_version())
+
+
+asyncio.run(main())
+```
+
+## Local token authentication
+
+Local authentication requires a token generated by the official mobile app and a local user on the OverKiz API platform.
+
+```python
+import asyncio
+
+from pyoverkiz.auth.credentials import LocalTokenCredentials
+from pyoverkiz.client import OverkizClient
+from pyoverkiz.utils import create_local_server_config
+
+
+async def main() -> None:
+    async with OverkizClient(
+        server=create_local_server_config(host="gateway-xxxx.local"),
+        credentials=LocalTokenCredentials("local-token"),
+        verify_ssl=False,
+    ) as client:
+        await client.login()
+        print(await client.get_api_version())
+
+
+asyncio.run(main())
+```
+
+## Token refresh behavior
+
+The client refreshes access tokens as needed during authenticated calls. If you see authentication errors, re-run `login()` before retrying the request.
+
+## Unsupported auth flows
+
+Some vendors use authentication flows that are not supported. In those cases, obtain a local token and use a local server configuration instead.
+
+## Secure storage tips
+
+- Use environment variables or a secret manager for tokens.
+- Avoid hard-coding credentials in source control.
+- Rotate tokens regularly if your vendor supports it.