Documentation overhaul

README.md

@@ -1,10 +1,9 @@
-# ONVIF Python
+# ONVIF Python [![Downloads](https://img.shields.io/pypi/dm/onvif-python?label=Downloads&style=plastic)](https://pepy.tech/projects/onvif-python)
 
 [![Python Version](https://img.shields.io/pypi/pyversions/onvif-python?logo=python&logoColor=white&color=blue&style=plastic&label=Python)](https://pypi.org/project/onvif-python)
 [![PyPI Version](https://img.shields.io/pypi/v/onvif-python?logo=pypi&logoColor=white&color=blue&style=plastic&label=PyPI)](https://pypi.org/project/onvif-python/)
 [![Quality](https://img.shields.io/codacy/grade/bff08a94e4d447b690cea49c6594826d?style=plastic&logo=codacy&label=Quality)](https://app.codacy.com/gh/nirsimetri/onvif-python/dashboard)
 [![Coverage](https://img.shields.io/codacy/coverage/bff08a94e4d447b690cea49c6594826d?style=plastic&logo=codacy&label=Coverage)](https://app.codacy.com/gh/nirsimetri/onvif-python/coverage)
-[![Downloads](https://img.shields.io/pepy/dt/onvif-python?label=Downloads&color=red&style=plastic)](https://pepy.tech/projects/onvif-python)
 <br>
 [![Build](https://img.shields.io/github/actions/workflow/status/nirsimetri/onvif-python/python-app.yml?logo=github&style=plastic&label=Build)](https://github.com/nirsimetri/onvif-python/actions/workflows/python-app.yml)
 [![Upload Python](https://img.shields.io/github/actions/workflow/status/nirsimetri/onvif-python/python-publish.yml?logo=github&style=plastic&label=Upload%20Package)](https://github.com/nirsimetri/onvif-python/actions/workflows/python-publish.yml)
@@ -18,16 +17,71 @@ Behind the scenes, ONVIF communication relies on **[SOAP](https://en.wikipedia.o
 This library simplifies that process by wrapping SOAP communication into a clean, Pythonic API. You no longer need to handle low-level XML parsing, namespaces, or security tokens manually; the library takes care of it, letting you focus on building functionality.
 
 ## Who Is It For?
-- **Individual developers** exploring ONVIF or building hobby projects  
-- **Companies** building video intelligence, analytics, or VMS platforms  
-- **Security integrators** who need reliable ONVIF interoperability across devices
+
+<table>
+  <tr>
+    <th align="start">
+    <img
+      src="https://github.com/Templarian/MaterialDesign/blob/master/svg/account-hard-hat.svg"
+      width="24"
+      height="24"
+      valign="middle"
+    />&nbsp;Individual Developers
+    </th>
+    <th align="start">
+    <img
+      src="https://github.com/Templarian/MaterialDesign/blob/master/svg/video-wireless.svg"
+      width="24"
+      height="24"
+      valign="middle"
+    />&nbsp;Platform Developers
+    </th>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <p>Explore ONVIF capabilities and build applications for IP cameras and compatible devices.</p>
+    </td>
+    <td width="50%" valign="top">
+      <p>Build video intelligence, analytics, and video management system (VMS) platforms.</p>
+    </td>
+  </tr>
+  <tr>
+    <th align="start">
+    <img
+      src="https://github.com/Templarian/MaterialDesign/blob/master/svg/cctv.svg"
+      width="24"
+      height="24"
+      valign="middle"
+    />&nbsp;Security Integrators
+    </th>
+    <th align="start">
+    <img
+      src="https://github.com/Templarian/MaterialDesign/blob/master/svg/chip.svg"
+      width="24"
+      height="24"
+      valign="middle"
+    />&nbsp;Device & IoT Engineers
+    </th>
+  </tr>
+  <tr>
+    <td width="50%" valign="top">
+      <p>Integrate security devices and troubleshoot ONVIF interoperability across vendors.</p>
+    </td>
+    <td width="50%" valign="top">
+      <p>Develop, test, and integrate ONVIF-compliant devices and IP-based physical security systems.</p>
+    </td>
+  </tr>
+</table>
 
 ## Requirements
 
-- **Python**: 3.10 or higher
-- **Dependencies**:
-  - [`zeep>=4.3.0`](https://github.com/mvantellingen/python-zeep) - SOAP client for ONVIF communication
-  - [`requests>=2.32.0`](https://github.com/psf/requests) - HTTP library for network requests
+Python **3.10 or higher** is required.
+
+## Dependencies
+
+- [zeep](https://github.com/mvantellingen/python-zeep) → SOAP client for ONVIF communication.
+- [requests](https://github.com/psf/requests) → HTTP library for network requests.
+- [pyreadline3](https://github.com/pyreadline3/pyreadline3) → Only installed on Windows (`win32`) for CLI auto-completion.
 
 ## Installation
 
@@ -36,6 +90,12 @@ From official [PyPI](https://pypi.org/project/onvif-python/):
 pip install --upgrade onvif-python
 ```
 
+Or install using [pipx](https://pipx.pypa.io/stable/) for an isolated environment:
+```shell
+pipx install git+https://github.com/nirsimetri/onvif-python
+
+```
+
 Or clone this repository and install locally:
 ```shell
 git clone https://github.com/nirsimetri/onvif-python

docs/api/core/index.md

@@ -0,0 +1,22 @@
+---
+hide:
+  - toc
+---
+
+# Core API
+
+<div class="grid cards" markdown>
+
+-   :material-lan-connect:{ .lg .middle }&nbsp; [**ONVIFClient**](onvif_client.md)
+
+    ---
+
+    Connect to ONVIF devices, configure connections and authentication, and manage service access.
+
+-   :material-connection:{ .lg .middle }&nbsp; [**ONVIFOperator**](onvif_operator.md)
+
+    ---
+
+    An **internal class** for coordinating ONVIF operations and managing service interactions.
+
+</div>

docs/api/core/onvif_client.md

@@ -1,7 +1,15 @@
-# ONVIFClient
+---
+comments: true
+---
 
 ::: onvif.client.ONVIFClient
     options:
+      show_root_heading: true
+      show_root_full_path: true
+      docstring_options:
+        ignore_init_summary: true
       show_source: true
       docstring_style: google
-      members_order: source
+      members_order: source
+      heading_level: 2
+      merge_init_into_class: true

docs/api/core/onvif_operator.md

@@ -1,7 +1,12 @@
-# ONVIFOperator
+---
+comments: true
+---
 
 ::: onvif.operator.ONVIFOperator
     options:
+      show_root_heading: true
+      show_root_full_path: true
       show_source: true
       docstring_style: google
-      members_order: source
+      members_order: source
+      heading_level: 2

docs/api/exceptions/index.md

@@ -0,0 +1,22 @@
+---
+hide:
+  - toc
+---
+
+# Exceptions
+
+<div class="grid cards" markdown>
+
+-   :material-alert-circle-outline:{ .lg .middle }&nbsp; [**ONVIFOperationException**](onvif_exception.md)
+
+    ---
+
+    Understand exceptions raised by failed ONVIF operations, including error details for diagnosing issues.
+
+-   :material-reload-alert:{ .lg .middle }&nbsp; [**Error Handlers**](onvif_error_handlers.md)
+
+    ---
+
+    Explore error-handling utilities for processing and managing errors consistently across ONVIF operations.
+
+</div>

docs/api/exceptions/onvif_error_handlers.md

@@ -1,7 +1,12 @@
-# Error Handlers
+---
+comments: true
+---
 
 ::: onvif.utils.error_handlers
     options:
+      show_root_heading: true
+      show_root_full_path: true
       show_source: true
       docstring_style: google
-      members_order: source
+      members_order: source
+      heading_level: 2

docs/api/exceptions/onvif_exception.md

@@ -1,7 +1,11 @@
-# ONVIFOperationException
+---
+comments: true
+---
 
 ::: onvif.utils.ONVIFOperationException
     options:
+      show_root_heading: true
+      show_root_full_path: true
       show_source: true
       docstring_style: google
       members_order: source

docs/api/index.md

@@ -0,0 +1,46 @@
+---
+hide:
+  - toc
+---
+
+# API Reference
+
+<div class="grid cards" markdown>
+
+-   :material-hub-outline:{ .lg .middle }&nbsp; **Core**
+
+    ---
+
+    Configure ONVIF connections and interact with devices through the main client interfaces.
+
+    ---
+    [<span class="icon-link">:octicons-arrow-right-24: Explore Core</span>](core/index.md)
+
+-   :material-alert-circle-outline:{ .lg .middle }&nbsp; **Exceptions**
+
+    ---
+
+    Understand operation exceptions and error-handling utilities for diagnosing and handling failures.
+
+    ---
+    [<span class="icon-link">:octicons-arrow-right-24: Explore Exceptions</span>](exceptions/index.md)
+
+-   :material-toolbox-outline:{ .lg .middle }&nbsp; **Utilities**
+
+    ---
+
+    Discover ONVIF devices, configure caching, manage WSDL resources, and extend service behavior.
+
+    ---
+    [<span class="icon-link">:octicons-arrow-right-24:  Explore Utilities</span>](utilities/index.md)
+
+-   :material-linked-services:{ .lg .middle }&nbsp; **Services**
+
+    ---
+
+    Browse the available ONVIF service clients, from device management, events, PTZ, analytics, and more.
+
+    ---
+    [<span class="icon-link">:octicons-arrow-right-24: Explore Services</span>](services/index.md)
+
+</div>