python-kasa · rytilahti · May 8, 2024 · May 5, 2024 · May 5, 2024 · May 7, 2024
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,4 @@
+# Contributing to python-kasa
+
+All types of contributions are very welcome.
+To make the process as straight-forward as possible, we have written [some instructions in our docs](https://python-miio.readthedocs.io/en/latest/contribute.html) to get you started.
diff --git a/README.md b/README.md
@@ -185,42 +185,12 @@ The device type specific documentation can be found in their separate pages:
 
 ## Contributing
 
-Contributions are very welcome! To simplify the process, we are leveraging automated checks and tests for contributions.
-
-### Setting up development environment
-
-To get started, simply clone this repository and initialize the development environment.
-We are using [poetry](https://python-poetry.org) for dependency management, so after cloning the repository simply execute
-`poetry install` which will install all necessary packages and create a virtual environment for you.
-
-### Code-style checks
-
-We use several tools to automatically check all contributions. The simplest way to verify that everything is formatted properly
-before creating a pull request, consider activating the pre-commit hooks by executing `pre-commit install`.
-This will make sure that the checks are passing when you do a commit.
-
-You can also execute the checks by running either `tox -e lint` to only do the linting checks, or `tox` to also execute the tests.
-
-### Running tests
-
-You can run tests on the library by executing `pytest` in the source directory.
-This will run the tests against contributed example responses, but you can also execute the tests against a real device:
-```
-$ pytest --ip <address>
-```
-Note that this will perform state changes on the device.
-
-### Analyzing network captures
-
-The simplest way to add support for a new device or to improve existing ones is to capture traffic between the mobile app and the device.
-After capturing the traffic, you can either use the [softScheck's  wireshark dissector](https://github.com/softScheck/tplink-smartplug#wireshark-dissector)
-or the `parse_pcap.py` script contained inside the `devtools` directory.
-Note, that this works currently only on kasa-branded devices which use port 9999 for communications.
-
+Contributions are very welcome! The easiest way to contribute is by [creating a fixture file](https://python-kasa.readthedocs.io/en/latest/contribute.html#contributing-fixture-files) for the automated test suite if your device hardware and firmware version is not currently listed as supported.
+Please refer to [our contributing guidelines](https://python-kasa.readthedocs.io/en/latest/contribute.html).
 
 ## Supported devices
 
-The following devices have been tested and confirmed as working. If your device is unlisted but working, please open a pull request to update the list and add a fixture file (use `python -m devtools.dump_devinfo` to generate one).
+The following devices have been tested and confirmed as working. If your device is unlisted but working, please consider [contributing a fixture file](https://python-kasa.readthedocs.io/en/latest/contribute.html#contributing-fixture-files).
 
 <!--Do not edit text inside the SUPPORTED section below -->
 <!--SUPPORTED_START-->

diff --git a/docs/source/contribute.md b/docs/source/contribute.md
@@ -0,0 +1,86 @@
+# Contributing
+
+You probably arrived to this page as you are interested in contributing to python-kasa in some form?
+All types of contributions are very welcome, so thank you!
+This page aims to help you to get started.
+
+```{contents} Contents
+   :local:
+```
+
+## Setting up the development environment
+
+To get started, simply clone this repository and initialize the development environment.
+We are using [poetry](https://python-poetry.org) for dependency management, so after cloning the repository simply execute
+`poetry install` which will install all necessary packages and create a virtual environment for you.
+
+```
+$ git clone https://github.com/python-kasa/python-kasa.git
+$ cd python-kasa
+$ poetry install
+```
+
+## Code-style checks
+
+We use several tools to automatically check all contributions as part of our CI pipeline.
+The simplest way to verify that everything is formatted properly
+before creating a pull request, consider activating the pre-commit hooks by executing `pre-commit install`.
+This will make sure that the checks are passing when you do a commit.
+
+```{note}
+You can also execute the pre-commit hooks on all files by executing `pre-commit run -a`
+```
+
+## Running tests
+
+You can run tests on the library by executing `pytest` in the source directory:
+
+```
+$ poetry run pytest kasa
+```
+
+This will run the tests against the contributed example responses.
+
+```{note}
+You can also execute the tests against a real device using `pytest --ip <address>`.
+Note that this will perform state changes on the device.
+```
+
+## Analyzing network captures
+
+The simplest way to add support for a new device or to improve existing ones is to capture traffic between the mobile app and the device.
+After capturing the traffic, you can either use the [softScheck's wireshark dissector](https://github.com/softScheck/tplink-smartplug#wireshark-dissector)
+or the `parse_pcap.py` script contained inside the `devtools` directory.
+Note, that this works currently only on kasa-branded devices which use port 9999 for communications.
+
+## Contributing fixture files
+
+One of the easiest ways to contribute is by creating a fixture file and uploading it for us.
+These files will help us to improve the library and run tests against devices that we have no access to.
+
+This library is tested against responses from real devices ("fixture files").
+These files contain responses for selected, known device commands and are stored [in our test suite](https://github.com/python-kasa/python-kasa/tree/master/kasa/tests/fixtures).
+
+You can generate these files by using the `dump_devinfo.py` script.
+Note, that this script should be run inside the main source directory so that the generated files are stored in the correct directories.
+The easiest way to do that is by doing:
+
+```
+$ git clone https://github.com/python-kasa/python-kasa.git
+$ cd python-kasa
+$ poetry install
+$ poetry shell
+$ python -m devtools.dump_devinfo --username <username> --password <password> --host 192.168.1.123
+```
+
+```{note}
+You can also execute the script against a network by using `--target`: `python -m devtools.dump_devinfo --target network 192.168.1.255`
+```
+
+The script will run queries against the device, and prompt at the end if you want to save the results.
+If you choose to do so, it will save the fixture files directly in their correct place to make it easy to create a pull request.
+
+```{note}
+When adding new fixture files, you should run `pre-commit run -a` to re-generate the list of supported devices.
+You may need to adjust `device_fixtures.py` to add a new model into the correct device categories.  Verify that test pass by executing `poetry run pytest kasa`.
+```
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -10,6 +10,7 @@
    discover
    smartdevice
    design
+   contribute
    smartbulb
    smartplug
    smartdimmer