Update documentation: remove outdated authentication guide and enhance getting started section

Author: iMicknl

docs/authentication.md

@@ -1,14 +1,15 @@
 # Getting started
 
+This guide will help you install the library, connect to your hub, and perform your first actions.
+
 ## Prerequisites
 
 - Python 3.10+
 - An OverKiz-compatible hub and account
 
-## Install pyOverkiz from PyPi
-
+## Install pyOverkiz from PyPI
 
-### With UV <small>recommended</small> { #with-uv data-toc-label="with uv" }
+### With UV <small>recommended</small>
 
 ```bash
 uv add pyoverkiz
@@ -27,78 +28,88 @@ Use a cloud server when you want to connect through the vendor’s public API. U
 - Cloud servers use the `Server` enum.
 - Local servers use `create_local_server_config` with a hostname or IP address.
 
-## First login (cloud)
+## Authentication
 
-```python
-import asyncio
+=== "Somfy (cloud)"
 
-from pyoverkiz.auth.credentials import UsernamePasswordCredentials
-from pyoverkiz.client import OverkizClient
-from pyoverkiz.enums import Server
+    Cloud authentication uses a vendor server from `Server` plus `UsernamePasswordCredentials`.
 
+    ```python
+    import asyncio
 
-async def main() -> None:
-    async with OverkizClient(
-        server=Server.SOMFY_EUROPE,
-        credentials=UsernamePasswordCredentials("you@example.com", "password"),
-    ) as client:
-        await client.login()
-        print(await client.get_setup())
+    from pyoverkiz.auth.credentials import UsernamePasswordCredentials
+    from pyoverkiz.client import OverkizClient
+    from pyoverkiz.enums import Server
 
 
-asyncio.run(main())
-```
+    async def main() -> None:
+        async with OverkizClient(
+            server=Server.SOMFY_EUROPE,
+            credentials=UsernamePasswordCredentials("you@example.com", "password"),
+        ) as client:
+            await client.login()
 
-## First login (local)
+    asyncio.run(main())
+    ```
 
-```python
-import asyncio
+=== "Somfy (local)"
 
-from pyoverkiz.auth.credentials import LocalTokenCredentials
-from pyoverkiz.client import OverkizClient
-from pyoverkiz.utils import create_local_server_config
+    Local authentication requires a token generated by the official mobile app and a local user on the OverKiz API platform.
 
+    ```python
+    import asyncio
 
-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_setup())
+    from pyoverkiz.auth.credentials import LocalTokenCredentials
+    from pyoverkiz.client import OverkizClient
+    from pyoverkiz.utils import create_local_server_config
 
 
-asyncio.run(main())
-```
+    async def main() -> None:
+        async with OverkizClient(
+            server=create_local_server_config(host="gateway-xxxx.local"),
+            credentials=LocalTokenCredentials("local-token"),
+            verify_ssl=True, # disable if you connect via IP
+        ) as client:
+            await client.login()
 
-## Sanity check: list devices
+    asyncio.run(main())
+    ```
 
-```python
-import asyncio
+=== "Cozytouch (cloud)"
 
-from pyoverkiz.auth.credentials import UsernamePasswordCredentials
-from pyoverkiz.client import OverkizClient
-from pyoverkiz.enums import Server
+    ```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("you@example.com", "password"),
-    ) as client:
-        await client.login()
-        devices = await client.get_devices()
-        for device in devices:
-            print(f"{device.label} ({device.id}) -> {device.widget}")
 
+    async def main() -> None:
+        async with OverkizClient(
+            server=Server.SOMFY_EUROPE,
+            credentials=UsernamePasswordCredentials("you@example.com", "password"),
+        ) as client:
+            await client.login()
 
-asyncio.run(main())
+    asyncio.run(main())
+    ```
 
-## Next steps
+=== "Rexel (cloud)"
 
-- Learn about authentication flows in [docs/authentication.md](docs/authentication.md).
-- Control devices and run actions in [docs/device-control.md](docs/device-control.md).
-- Handle events in [docs/event-handling.md](docs/event-handling.md).
-- Understand errors in [docs/error-handling.md](docs/error-handling.md).
-```
+    ```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("you@example.com", "password"),
+        ) as client:
+            await client.login()
+
+    asyncio.run(main())
+    ```

docs/getting-started.md

@@ -4,7 +4,11 @@ hide:
   - toc
   - title
 ---
-# pyOverkiz
+<style>
+  .md-content__inner > h1:first-of-type {
+    display: none;
+  }
+</style>
 
 pyOverkiz is an async Python library for interacting with Overkiz-based platforms, including Somfy and Atlantic. It enables authentication, device discovery, state reading, command execution, and real-time event streaming from supported gateways.
 

docs/index.md

@@ -35,12 +35,14 @@ markdown_extensions:
   - pymdownx.superfences
   - pymdownx.tasklist
   - admonition
+  - pymdownx.superfences
+  - pymdownx.tabbed:
+      alternate_style: true
 
 nav:
   - Overview: index.md
   - User Guide:
       - Getting started: getting-started.md
-      - Authentication: authentication.md
       - Core concepts: core-concepts.md
       - Device control: device-control.md
       - Event handling: event-handling.md