From 2912ba662cbe5d23289bb3df17a3b2d673cff2e2 Mon Sep 17 00:00:00 2001 From: Stefanie Jane Date: Sun, 21 Jul 2024 10:17:11 -0700 Subject: [PATCH] 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 | 62 +++++++++++++++++ README.md | 20 +++--- docs/api/client.md | 59 ++++++++++++++++ docs/api/models.md | 93 +++++++++++++++++++++++++ docs/contributing.md | 115 ++++++++++++++++++++++++++++++ docs/development.md | 143 ++++++++++++++++++++++++++++++++++++++ docs/index.md | 40 +++++++++++ docs/installation.md | 40 +++++++++++ docs/usage/cli.md | 85 ++++++++++++++++++++++ docs/usage/library.md | 96 +++++++++++++++++++++++++ examples/effect_cycler.py | 56 +++++++++++++++ mkdocs.yml | 48 +++++++++++++ pyproject.toml | 3 + scripts/release.sh | 9 ++- signalrgb/__init__.py | 1 + 15 files changed, 857 insertions(+), 13 deletions(-) create mode 100644 docs/api/client.md create mode 100644 docs/api/models.md create mode 100644 docs/contributing.md create mode 100644 docs/development.md create mode 100644 docs/index.md create mode 100644 docs/installation.md create mode 100644 docs/usage/cli.md create mode 100644 docs/usage/library.md create mode 100644 examples/effect_cycler.py create mode 100644 mkdocs.yml diff --git a/.circleci/config.yml b/.circleci/config.yml index 1f13c8f..7fb3683 100644 --- a/.circleci/config.yml +++ b/.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 "ci-bot@hyperbliss.tech" + 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 git@github.com: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]+)*/ diff --git a/README.md b/README.md index c8f92a1..a63d4aa 100755 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# 🌈 SignalRGB Python Client +# 🌈 signalrgb-python
@@ -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
-📚 [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)
@@ -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)! ☕ -
\ No newline at end of file + diff --git a/docs/api/client.md b/docs/api/client.md new file mode 100644 index 0000000..700e6a4 --- /dev/null +++ b/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. diff --git a/docs/api/models.md b/docs/api/models.md new file mode 100644 index 0000000..3434102 --- /dev/null +++ b/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. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 0000000..33f3e29 --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,115 @@ +## What should I know before I get started? + +### Project Structure + +* `signalrgb/` - This directory contains the main source code for the project. +* `tests/` - This directory contains all the tests. +* `docs/` - This directory contains the project documentation. +* `examples/` - This directory contains example scripts demonstrating how to use the library. + +## How Can I Contribute? + +### Reporting Bugs + +This section guides you through submitting a bug report for signalrgb-python. Following these guidelines helps maintainers and the community understand your report, reproduce the behavior, and find related reports. + +* Use a clear and descriptive title for the issue to identify the problem. +* Describe the exact steps which reproduce the problem in as many details as possible. +* Provide specific examples to demonstrate the steps. +* Describe the behavior you observed after following the steps and point out what exactly is the problem with that behavior. +* Explain which behavior you expected to see instead and why. +* Include screenshots and animated GIFs which show you following the described steps and clearly demonstrate the problem. + +### Suggesting Enhancements + +This section guides you through submitting an enhancement suggestion for signalrgb-python, including completely new features and minor improvements to existing functionality. + +* Use a clear and descriptive title for the issue to identify the suggestion. +* Provide a step-by-step description of the suggested enhancement in as many details as possible. +* Provide specific examples to demonstrate the steps. +* Describe the current behavior and explain which behavior you expected to see instead and why. +* Explain why this enhancement would be useful to most signalrgb-python users. +* List some other text editors or applications where this enhancement exists. + +### Your First Code Contribution + +Unsure where to begin contributing to signalrgb-python? You can start by looking through these `beginner` and `help-wanted` issues: + +* [Beginner issues](https://github.com/hyperb1iss/signalrgb-python/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) - issues which should only require a few lines of code, and a test or two. +* [Help wanted issues](https://github.com/hyperb1iss/signalrgb-python/issues?q=is%3Aissue+is%3Aopen+label%3A%22help+wanted%22) - issues which should be a bit more involved than `beginner` issues. + +### Pull Requests + +* Fill in [the required template](PULL_REQUEST_TEMPLATE.md) +* Do not include issue numbers in the PR title +* Follow the [Python style guide](https://www.python.org/dev/peps/pep-0008/) +* Include thoughtfully-worded, well-structured tests in the `./tests` folder. Run them using `pytest`. +* Document new code based on the [Documentation Styleguide](#documentation-styleguide) +* End all files with a newline + +## Styleguides + +### Git Commit Messages + +* Use the present tense ("Add feature" not "Added feature") +* Use the imperative mood ("Move cursor to..." not "Moves cursor to...") +* Limit the first line to 72 characters or less +* Reference issues and pull requests liberally after the first line +* Consider starting the commit message with an applicable emoji: + * :art: `:art:` when improving the format/structure of the code + * :racehorse: `:racehorse:` when improving performance + * :non-potable_water: `:non-potable_water:` when plugging memory leaks + * :memo: `:memo:` when writing docs + * :penguin: `:penguin:` when fixing something on Linux + * :apple: `:apple:` when fixing something on macOS + * :checkered_flag: `:checkered_flag:` when fixing something on Windows + * :bug: `:bug:` when fixing a bug + * :fire: `:fire:` when removing code or files + * :green_heart: `:green_heart:` when fixing the CI build + * :white_check_mark: `:white_check_mark:` when adding tests + * :lock: `:lock:` when dealing with security + * :arrow_up: `:arrow_up:` when upgrading dependencies + * :arrow_down: `:arrow_down:` when downgrading dependencies + * :shirt: `:shirt:` when removing linter warnings + +### Python Styleguide + +All Python code must adhere to [PEP 8](https://www.python.org/dev/peps/pep-0008/). + +### Documentation Styleguide + +* Use [Markdown](https://daringfireball.net/projects/markdown/). +* Use [Google-style docstrings](https://sphinxcontrib-napoleon.readthedocs.io/en/latest/example_google.html) for Python code. + +## Additional Notes + +### Issue and Pull Request Labels + +This section lists the labels we use to help us track and manage issues and pull requests. + +[GitHub search](https://help.github.com/articles/searching-issues/) makes it easy to use labels for finding groups of issues or pull requests you're interested in. + +#### Type of Issue and Issue State + +* `bug` - Issues that are bugs. +* `enhancement` - Issues that are feature requests. +* `question` - Issues that are questions. +* `duplicate` - Issues that are duplicates of other issues. +* `good first issue` - Issues that are good for newcomers. +* `help wanted` - Issues that need assistance from the community. + +#### Topic Categories + +* `documentation` - Issues related to documentation. +* `performance` - Issues related to performance. +* `security` - Issues related to security. + +#### Pull Request Labels + +* `work-in-progress` - Pull requests that are still being worked on, more changes will follow. +* `needs-review` - Pull requests that need code review and approval from maintainers. +* `under-review` - Pull requests being reviewed by maintainers. +* `requires-changes` - Pull requests that need to be updated based on review comments and then reviewed again. +* `needs-testing` - Pull requests that need manual testing. + +Thank you for your contributions to signalrgb-python! diff --git a/docs/development.md b/docs/development.md new file mode 100644 index 0000000..fb77174 --- /dev/null +++ b/docs/development.md @@ -0,0 +1,143 @@ +# Development Guide + +This guide will help you set up your development environment for contributing to signalrgb-python. + +## Prerequisites + +Before you begin, ensure you have the following installed on your system: + +- Python 3.12 or higher +- [Poetry](https://python-poetry.org/docs/#installation) for dependency management +- Git for version control + +## Setting Up the Development Environment + +1. Clone the repository: + ```bash + git clone https://github.com/hyperb1iss/signalrgb-python.git + cd signalrgb-python + ``` + +2. Install the project dependencies using Poetry: + ```bash + poetry install + ``` + +3. Activate the virtual environment: + ```bash + poetry shell + ``` + +## Running Tests + +We use pytest for our test suite. To run the tests: + +```bash +poetry run pytest +``` + +To run tests with coverage report: + +```bash +poetry run pytest --cov=signalrgb --cov-report=term-missing +``` + +## Linting + +We use Ruff for linting and formatting. To run the linter: + +```bash +poetry run ruff check . +``` + +To automatically fix linting issues: + +```bash +poetry run ruff check --fix . +``` + +## Type Checking + +We use mypy for static type checking. To run the type checker: + +```bash +poetry run mypy signalrgb +``` + +## Pre-commit Hooks + +We use pre-commit hooks to ensure code quality before committing. To set up pre-commit hooks: + +1. Install pre-commit: + ```bash + poetry run pre-commit install + ``` + +2. Run pre-commit on all files: + ```bash + poetry run pre-commit run --all-files + ``` + +The pre-commit hooks will now run automatically on `git commit`. + +## Building Documentation + +To build the documentation locally: + +1. Install the documentation dependencies: + ```bash + poetry add mkdocs mkdocs-material mkdocstrings[python] + ``` + +2. Build and serve the documentation: + ```bash + poetry run mkdocs serve + ``` + +3. Open your browser and navigate to `http://127.0.0.1:8000/` to view the documentation. + +## Creating a New Release + +1. Update the version number in `pyproject.toml`: + ```bash + poetry version patch # or minor, or major + ``` + +2. Update the `CHANGELOG.md` file with the changes for the new version. + +3. Commit the changes: + ```bash + git add pyproject.toml CHANGELOG.md + git commit -m "Bump version to x.y.z" + ``` + +4. Create a new tag: + ```bash + git tag -a vx.y.z -m "Release version x.y.z" + ``` + +5. Push the changes and the new tag: + ```bash + git push origin main --tags + ``` + +The CI/CD pipeline will handle the rest, including building and publishing the package to PyPI and deploying the updated documentation. + +## Troubleshooting + +If you encounter any issues during development, please check the following: + +1. Ensure you're using the correct version of Python (3.12+). +2. Make sure all dependencies are up to date (`poetry update`). +3. Check that your virtual environment is activated (`poetry shell`). +4. Clear any cached files: `find . -name '*.pyc' -delete` and `find . -name '__pycache__' -type d -delete` + +If you're still having problems, please open an issue on the GitHub repository with a detailed description of the problem and steps to reproduce it. + +## Getting Help + +If you need help with development, you can: + +1. Open an issue on the GitHub repository. +2. Reach out to the maintainers directly (contact information can be found in the `README.md` file). + diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..122a9ab --- /dev/null +++ b/docs/index.md @@ -0,0 +1,40 @@ +# signalrgb-python + +Welcome to the documentation for signalrgb-python. This library provides a powerful and easy-to-use interface for controlling [SignalRGB Pro](https://signalrgb.com) through both a command-line interface (CLI) and a Python library. + +## Features + +- 📋 List available lighting effects +- 🔍 Get detailed information about specific effects +- 🎨 Apply effects to your devices with ease +- 🖥️ User-friendly command-line interface +- 🐍 Python client library for seamless integration into your projects +- 🔐 Error handling and connection management +- 🔄 Automatic effect caching for improved performance + +## Quick Start + +Install signalrgb-python: + +```bash +pip install signalrgb +``` + +Use the CLI to list available effects: + +```bash +signalrgb list-effects +``` + +Or use the Python library in your code: + +```python +from signalrgb.client import SignalRGBClient + +client = SignalRGBClient() +effects = client.get_effects() +for effect in effects: + print(f"Effect: {effect.attributes.name}") +``` + +For more detailed information, check out the [Installation](installation.md) and [Usage](usage/cli.md) guides. diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 0000000..7e0ecf9 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,40 @@ +# Installation + +## Prerequisites + +Before installing signalrgb-python, ensure you have the following: + +- Python 3.12 or higher +- [SignalRGB Pro](https://www.signalrgb.com/pro/) (required for API access) + +This library uses the [SignalRGB REST API](https://docs.signalrgb.com/signalrgb-api), which is only available in SignalRGB Pro. + +## Installing with pip + +The easiest way to install signalrgb-python is using pip: + +```bash +pip install signalrgb +``` + +## Installing with Poetry + +If you prefer to use Poetry for dependency management: + +```bash +poetry add signalrgb +``` + +## Verifying the Installation + +After installation, you can verify that signalrgb-python is correctly installed by running: + +```bash +signalrgb --version +``` + +This should display the version number of the installed client. + +## Next Steps + +Now that you have installed signalrgb-python, you can start using it. Check out the [CLI Usage](usage/cli.md) guide to learn how to use the command-line interface, or the [Python Library Usage](usage/library.md) guide to learn how to integrate it into your Python projects. diff --git a/docs/usage/cli.md b/docs/usage/cli.md new file mode 100644 index 0000000..3ef35bf --- /dev/null +++ b/docs/usage/cli.md @@ -0,0 +1,85 @@ +# Command-Line Interface (CLI) Usage + +signalrgb-python provides a user-friendly command-line interface for interacting with your SignalRGB setup. This guide covers the basic usage of the CLI. + +## Basic Syntax + +The basic syntax for using the SignalRGB CLI is: + +```bash +signalrgb [OPTIONS] COMMAND [ARGS]... +``` + +You can always use the `--help` option to get more information about available commands and options: + +```bash +signalrgb --help +``` + +## Available Commands + +### List Effects + +To list all available lighting effects: + +```bash +signalrgb list-effects +``` + +### Get Effect Details + +To get detailed information about a specific effect: + +```bash +signalrgb get-effect "Effect Name" +``` + +Replace "Effect Name" with the name of the effect you want to inspect. + +### Apply an Effect + +To apply a specific effect: + +```bash +signalrgb apply-effect "Effect Name" +``` + +### Get Current Effect + +To see which effect is currently active: + +```bash +signalrgb current-effect +``` + +## Global Options + +You can specify a custom host and port for all commands: + +```bash +signalrgb --host my-pc.local --port 16038 list-effects +``` + +## Examples + +Here are some example use cases: + +1. List all effects and pipe the output to `grep` to find a specific effect: + + ```bash + signalrgb list-effects | grep "Electric Space" + ``` + +2. Apply the "Rave Visualizer" effect: + + ```bash + signalrgb apply-effect "Rave Visualizer" + ``` + +3. Get details of the current effect and save it to a file: + + ```bash + signalrgb current-effect > current_effect.txt + ``` + +Remember to refer to the `--help` option for each command to see all available options and arguments. diff --git a/docs/usage/library.md b/docs/usage/library.md new file mode 100644 index 0000000..383f339 --- /dev/null +++ b/docs/usage/library.md @@ -0,0 +1,96 @@ +# Python Library Usage + +signalrgb-python can be easily integrated into your Python projects. This guide covers the basic usage of the library. + +## Initializing the Client + +First, import the `SignalRGBClient` class and create an instance: + +```python +from signalrgb import SignalRGBClient + +client = SignalRGBClient(host="localhost", port=16038) +``` + +You can specify a custom host and port if your SignalRGB instance is not running on the default location. + +## Listing Effects + +To get a list of all available effects: + +```python +effects = client.get_effects() +for effect in effects: + print(f"Effect: {effect.attributes.name}") +``` + +## Getting Effect Details + +To get detailed information about a specific effect: + +```python +effect = client.get_effect_by_name("Rain") +print(f"Effect Name: {effect.attributes.name}") +print(f"Description: {effect.attributes.description}") +print(f"Uses Audio: {effect.attributes.uses_audio}") +``` + +## Applying an Effect + +To apply a specific effect: + +```python +client.apply_effect_by_name("Rainbow Wave") +``` + +## Getting the Current Effect + +To see which effect is currently active: + +```python +current_effect = client.get_current_effect() +print(f"Current Effect: {current_effect.attributes.name}") +``` + +## Error Handling + +The client provides custom exceptions for different types of errors. You can handle these exceptions to provide better error messages or implement retry logic: + +```python +from signalrgb import SignalRGBClient, ConnectionError, APIError, EffectNotFoundError + +client = SignalRGBClient() + +try: + client.apply_effect_by_name("Non-existent Effect") +except ConnectionError as e: + print(f"Connection failed: {e}") +except EffectNotFoundError as e: + print(f"Effect not found: {e}") +except APIError as e: + print(f"API error occurred: {e}") +``` + +## Advanced Usage + +### Refreshing Effects Cache + +The client caches the list of effects for performance. If you need to refresh this cache: + +```python +client.refresh_effects() +``` + +### Working with Effect Parameters + +Some effects have parameters that can be adjusted. You can access these parameters like this: + +```python +effect = client.get_effect_by_name("Falling Stars") +parameters = effect.attributes.parameters +print(f"Effect Parameters: {parameters}") +``` + +Note that the structure of parameters can vary between effects. Always check the specific effect's documentation or inspect the parameters dictionary to understand what options are available. + +Remember to handle exceptions and implement proper error checking in your production code to ensure robustness and good user experience. diff --git a/examples/effect_cycler.py b/examples/effect_cycler.py new file mode 100644 index 0000000..65b731e --- /dev/null +++ b/examples/effect_cycler.py @@ -0,0 +1,56 @@ +import time +from signalrgb.client import SignalRGBClient + + +def cycle_effects(client, duration=10): + """ + Cycle through all available effects, applying each for a specified duration. + + Args: + client (SignalRGBClient): An initialized SignalRGBClient object. + duration (int): The duration in seconds to apply each effect. Defaults to 10 seconds. + """ + print("Fetching available effects...") + effects = client.get_effects() + + print(f"Found {len(effects)} effects. Starting cycle...") + for effect in effects: + effect_name = effect.attributes.name + print(f"Applying effect: {effect_name}") + + try: + client.apply_effect_by_name(effect_name) + print( + f"Effect '{effect_name}' applied successfully. Waiting for {duration} seconds..." + ) + time.sleep(duration) + except Exception as e: + print(f"Error applying effect '{effect_name}': {str(e)}") + + +def main(): + # Initialize the SignalRGB client + client = SignalRGBClient(host="hyperia.home", port=16038) + + try: + # Get the initial effect + initial_effect = client.get_current_effect() + print(f"Initial effect: {initial_effect.attributes.name}") + + # Cycle through effects + cycle_effects(client, duration=5) # Change duration as needed + + except Exception as e: + print(f"An error occurred: {str(e)}") + + finally: + # Restore the initial effect + try: + client.apply_effect_by_name(initial_effect.attributes.name) + print(f"Restored initial effect: {initial_effect.attributes.name}") + except Exception as e: + print(f"Error restoring initial effect: {str(e)}") + + +if __name__ == "__main__": + main() diff --git a/mkdocs.yml b/mkdocs.yml new file mode 100644 index 0000000..0aa283c --- /dev/null +++ b/mkdocs.yml @@ -0,0 +1,48 @@ +site_name: signalrgb-python +site_description: A Python client library and CLI for controlling SignalRGB Pro +repo_url: https://github.com/hyperb1iss/signalrgb-python +theme: + name: material + palette: + primary: indigo + accent: pink + features: + - navigation.tabs + - navigation.sections + - toc.integrate + - search.suggest + - search.highlight + - content.tabs.link + - content.code.annotation + - content.code.copy +markdown_extensions: + - pymdownx.highlight: + anchor_linenums: true + - pymdownx.inlinehilite + - pymdownx.snippets + - pymdownx.superfences + - admonition + - pymdownx.details + - pymdownx.tabbed: + alternate_style: true + - tables +nav: + - Home: index.md + - Installation: installation.md + - Usage: + - CLI: usage/cli.md + - Python Library: usage/library.md + - API Reference: + - Client: api/client.md + - Models: api/models.md + - Development: development.md + - Contributing: contributing.md +plugins: + - search + - mkdocstrings: + handlers: + python: + paths: [.] + options: + docstring_style: google + show_source: true diff --git a/pyproject.toml b/pyproject.toml index 0f6a254..d7340e5 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -17,6 +17,9 @@ pre-commit = "^3.7.1" [tool.poetry.group.dev.dependencies] pytest = "^8.2.2" +mkdocs = "^1.6.0" +mkdocs-material = "^9.5.29" +mkdocstrings = {extras = ["python"], version = "^0.25.1"} [build-system] requires = ["poetry-core"] diff --git a/scripts/release.sh b/scripts/release.sh index 67166c7..b3e21e0 100755 --- a/scripts/release.sh +++ b/scripts/release.sh @@ -16,12 +16,15 @@ read -p "Current version is $current_version. What should the new version be? " # Update the version in pyproject.toml poetry version $new_version +# Update documentation version +sed -i "s/version: $current_version/version: $new_version/" docs/index.md + # Commit the changes -git add pyproject.toml -git commit -m "Release: $new_version" +git add pyproject.toml docs/index.md +git commit -m ":bookmark: Release: $new_version" # Create and push the new tag git tag -a v$new_version -m "Release: $new_version" git push origin main --tags -echo "Release $new_version has been created and pushed. CircleCI will handle the rest." +echo "Release $new_version has been created and pushed. CircleCI will handle the rest, including documentation deployment." diff --git a/signalrgb/__init__.py b/signalrgb/__init__.py index e69de29..9c75f01 100644 --- a/signalrgb/__init__.py +++ b/signalrgb/__init__.py @@ -0,0 +1 @@ +"""Base package for signalrgb-python"""