Documentation using mkdocs

 * Add full project documentation
 * Add examples
 * Use consistent naming for the project
 * Automatically build and deploy to gh-pages via CircleCI

.circleci/config.yml

@@ -17,6 +17,53 @@ jobs:
       - store_test_results:
           path: test-results
 
+  build-docs:
+    docker:
+      - image: cimg/python:3.12
+    steps:
+      - checkout
+      - python/install-packages:
+          pkg-manager: poetry
+      - run:
+          name: Install MkDocs and plugins
+          command: poetry add mkdocs mkdocs-material mkdocstrings[python]
+      - run:
+          name: Build documentation
+          command: poetry run mkdocs build
+      - persist_to_workspace:
+          root: .
+          paths:
+            - site
+
+  deploy-docs:
+    docker:
+      - image: cimg/base:stable
+    steps:
+      - checkout
+      - attach_workspace:
+          at: .
+      - run:
+          name: Deploy to GitHub Pages
+          command: |
+            ls -al
+            git clone -b gh-pages https://github.com/hyperb1iss/signalrgb-python.git gh-pages
+            rm -rf gh-pages/*
+            mv -f site/* gh-pages/
+            pushd gh-pages
+            git config user.email "[email protected]"
+            git config user.name "signalrgb-python CI bot"
+            git add .
+            echo "commit"
+            if ! git diff-index --quiet HEAD; then
+            git commit -m ":books: Update documentation for ${CIRCLE_TAG} [skip ci]"
+              echo "push to github"
+              GIT_SSH_COMMAND="ssh -o StrictHostKeyChecking=accept-new" git push [email protected]:hyperb1iss/signalrgb-python.git gh-pages
+            else
+              echo "nothing to deploy"
+            fi
+            echo "done"
+            popd
+
   release:
     docker:
       - image: cimg/python:3.12
@@ -49,9 +96,24 @@ workflows:
           filters:
             tags:
               only: /.*/
+      - build-docs:
+          requires:
+            - build-and-test
+          filters:
+            tags:
+              only: /.*/
+      - deploy-docs:
+          requires:
+            - build-docs
+          filters:
+            tags:
+              only: /v[0-9]+(\.[0-9]+)*/
+            branches:
+              ignore: /.*/
       - release:
           requires:
             - build-and-test
+            - deploy-docs
           filters:
             tags:
               only: /v[0-9]+(\.[0-9]+)*/

README.md

@@ -1,4 +1,4 @@
-# 🌈 SignalRGB Python Client
+# 🌈 signalrgb-python
 
 <div align="center">
 
@@ -24,7 +24,7 @@
 
 ## 💻 Installation
 
-You can install the SignalRGB Python Client using pip:
+You can install signalrgb-python using pip:
 
 ```bash
 pip install signalrgb
@@ -47,7 +47,7 @@ This library uses the [SignalRGB REST API](https://docs.signalrgb.com/signalrgb-
 
 ### Command-line Interface
 
-The SignalRGB Python Client comes with an intuitive command-line interface for easy interaction with your SignalRGB setup.
+signalrgb-python comes with an intuitive command-line interface for easy interaction with your SignalRGB setup.
 
 ```bash
 # List all available effects
@@ -77,10 +77,10 @@ signalrgb --help
 
 ### Python Library
 
-Integrate the SignalRGB Python Client into your own Python projects with ease:
+Integrate signalrgb-python into your own Python projects with ease:
 
 ```python
-from signalrgb import SignalRGBClient
+from signalrgb.client import SignalRGBClient
 
 # Initialize the client
 client = SignalRGBClient(host="hyperia.home", port=16038)
@@ -103,7 +103,7 @@ print(f"Current effect: {current_effect.attributes.name}")
 The client provides custom exceptions for different types of errors:
 
 ```python
-from signalrgb import SignalRGBClient, ConnectionError, APIError, EffectNotFoundError
+from signalrgb.client import SignalRGBClient, ConnectionError, APIError, EffectNotFoundError
 
 client = SignalRGBClient()
 
@@ -119,7 +119,7 @@ except APIError as e:
 
 ## 📘 API Reference
 
-For detailed information about the available methods and classes, please refer to our [API Documentation](https://signalrgb-python.readthedocs.io).
+For detailed information about the available methods and classes, please refer to our [API Documentation](https://hyperb1iss.github.io/signalrgb-python/).
 
 ## 🛠️ Development
 
@@ -148,7 +148,7 @@ flake8
 
 ## 👥 Contributing
 
-We welcome contributions from the community! Here's how you can help:
+Have a fix or new feature that you want to add? That's amazing! You're amazing!
 
 1. Fork the repository
 2. Create a new branch: `git checkout -b feature-branch-name`
@@ -167,7 +167,7 @@ This project is licensed under the Apache License 2.0. See the [LICENSE](LICENSE
 
 <div align="center">
 
-📚 [Documentation](https://signalrgb-python.readthedocs.io) • 🐛 [Report Bug](https://github.com/hyperb1iss/signalrgb-python/issues) • 💡 [Request Feature](https://github.com/hyperb1iss/signalrgb-python/issues)
+📚 [Documentation](https://hyperb1iss.github.io/signalrgb-python/) • 🐛 [Report Bug](https://github.com/hyperb1iss/signalrgb-python/issues) • 💡 [Request Feature](https://github.com/hyperb1iss/signalrgb-python/issues)
 
 </div>
 
@@ -183,4 +183,4 @@ Created by [Stefanie Jane 🌠](https://github.com/hyperb1iss)
 
 If you find this project helpful, consider [buying me a coffee](https://ko-fi.com/hyperb1iss)! ☕
 
-</div>
+</div>

docs/api/client.md

@@ -0,0 +1,59 @@
+# SignalRGB Client API Reference
+
+This page provides detailed API documentation for the `SignalRGBClient` class, which is the main interface for interacting with the SignalRGB API.
+
+## SignalRGBClient
+
+::: signalrgb.client.SignalRGBClient
+    options:
+      show_root_heading: true
+      show_source: true
+
+## Exceptions
+
+The SignalRGB client defines several custom exceptions for error handling:
+
+::: signalrgb.client.SignalRGBException
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: signalrgb.client.ConnectionError
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: signalrgb.client.APIError
+    options:
+      show_root_heading: true
+      show_source: true
+
+::: signalrgb.client.EffectNotFoundError
+    options:
+      show_root_heading: true
+      show_source: true
+
+## Usage Example
+
+Here's a basic example of how to use the SignalRGBClient:
+
+```python
+from signalrgb import SignalRGBClient
+
+# Initialize the client
+client = SignalRGBClient(host="localhost", port=16038)
+
+# Get all effects
+effects = client.get_effects()
+for effect in effects:
+    print(f"Effect: {effect.attributes.name}")
+
+# Apply an effect
+client.apply_effect_by_name("Rainbow Wave")
+
+# Get current effect
+current_effect = client.get_current_effect()
+print(f"Current effect: {current_effect.attributes.name}")
+```
+
+For more detailed usage examples, please refer to the [Python Library Usage](../usage/library.md) guide.

docs/api/models.md

@@ -0,0 +1,93 @@
+# SignalRGB Models API Reference
+
+This page provides detailed API documentation for the data models used in the SignalRGB Python client. These models represent various data structures used in the SignalRGB API, including effects, responses, and error information.
+
+## Attributes
+
+::: signalrgb.model.Attributes
+    options:
+      show_root_heading: true
+      show_source: true
+
+## Links
+
+::: signalrgb.model.Links
+    options:
+      show_root_heading: true
+      show_source: true
+
+## Effect
+
+::: signalrgb.model.Effect
+    options:
+      show_root_heading: true
+      show_source: true
+
+## EffectList
+
+::: signalrgb.model.EffectList
+    options:
+      show_root_heading: true
+      show_source: true
+
+## Error
+
+::: signalrgb.model.Error
+    options:
+      show_root_heading: true
+      show_source: true
+
+## SignalRGBResponse
+
+::: signalrgb.model.SignalRGBResponse
+    options:
+      show_root_heading: true
+      show_source: true
+
+## EffectDetailsResponse
+
+::: signalrgb.model.EffectDetailsResponse
+    options:
+      show_root_heading: true
+      show_source: true
+
+## EffectListResponse
+
+::: signalrgb.model.EffectListResponse
+    options:
+      show_root_heading: true
+      show_source: true
+
+## Usage Example
+
+Here's a basic example of how to work with these models:
+
+```python
+from signalrgb import SignalRGBClient
+from signalrgb.model import Effect, Attributes
+
+# Initialize the client
+client = SignalRGBClient()
+
+# Get an effect
+effect: Effect = client.get_effect_by_name("Sakura")
+
+# Access effect attributes
+print(f"Effect name: {effect.attributes.name}")
+print(f"Effect description: {effect.attributes.description}")
+print(f"Effect uses audio: {effect.attributes.uses_audio}")
+
+# Create a new effect (note: this is just an example, you can't actually create new effects via the API)
+new_effect = Effect(
+    id="custom_effect_1",
+    type="lighting",
+    links=Links(apply="/api/v1/effects/custom_effect_1/apply"),
+    attributes=Attributes(
+        name="My Custom Effect",
+        description="A custom lighting effect",
+        uses_audio=True
+    )
+)
+```
+
+For more detailed usage examples, please refer to the [Python Library Usage](../usage/library.md) guide.