Use MkDocs for documentation (#592)

Author: hahn-th

.github/workflows/build-docs.yml

@@ -17,15 +17,16 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
+          pip install -r requirements.txt
           pip install -r requirements_docs.txt
           pip install -e .
-      - name: Sphinx build
+      - name: Build and deploy documentation
         run: |
-          sphinx-build docs/source docs/build/html
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          publish_branch: gh-pages
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/build/html
-          force_orphan: true
+          make publish
+#      - name: Build and Deploy to GitHub Pages
+#        uses: peaceiris/actions-gh-pages@v3
+#        with:
+#          publish_branch: gh-pages
+#          github_token: ${{ secrets.GITHUB_TOKEN }}
+#          publish_dir: docs/build/html
+#          force_orphan: true

.github/workflows/publish.yml

@@ -71,15 +71,9 @@ jobs:
       - name: Install dependencies
         run: |
           python -m pip install --upgrade pip
+          pip install -r requirements.txt
           pip install -r requirements_docs.txt
           pip install -e .
-      - name: Sphinx build
+      - name: Build and deploy documentation
         run: |
-          sphinx-build docs/source docs/build/html
-      - name: Deploy to GitHub Pages
-        uses: peaceiris/actions-gh-pages@v3
-        with:
-          publish_branch: gh-pages
-          github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: docs/build/html
-          force_orphan: true
+          make publish

.gitignore

@@ -2,7 +2,6 @@
 __pycache__/
 *.py[cod]
 *$py.class
-
 # C extensions
 *.so
 
@@ -67,7 +66,6 @@ docs/_build/
 target/
 
 # IPython Notebook
-.ipynb_checkpoints
 
 # pyenv
 .python-version
@@ -114,3 +112,4 @@ venv*/
 #own config file
 homematic.ini
 src/homematicip/_version.py
+/site/

Makefile

@@ -0,0 +1,26 @@
+# Makefile for HomematicIP Cloud Rest API Wrapper
+
+.PHONY: install test docs serve clean publish
+
+install:
+	pip install -r requirements.txt
+	pip install -r requirements_dev.txt
+	pip install -r requirements_docs.txt
+
+test:
+	pytest
+
+docs:
+	cp CHANGELOG.md ./docs/changelog.md
+	mkdocs build
+
+serve:
+	cp CHANGELOG.md ./docs/changelog.md
+	mkdocs serve
+
+publish:
+	cp CHANGELOG.md ./docs/changelog.md
+	mkdocs gh-deploy --force
+
+clean:
+	rm -rf site

docs/Makefile

@@ -0,0 +1,17 @@
+# API Introduction_old
+
+There are a few key classes for communication with the Rest API of HomematicIP.
+
+- **Home:** The most important object as it has the "overview" of the installation
+- **Group:** A group of devices for a specific need. E.g. Heating group, security group, ...
+- **MetaGroup:** A collection of groups. In the HomematicIP App this is called a "Room"
+- **Device:** A hardware device e.g. shutter contact, heating thermostat, alarm siren, ...
+- **FunctionChannel:** A channel of a device. For example DoorLockChannel for DoorLockDrive or **DimmerChannel**. A device has multiple channels - depending on its functions.
+
+For example:
+The device HmIP-DLD is represented by the class **DoorLockDrive** (or AsyncDoorLockDrive). The device has multiple channels.
+The base channel holds information about the device and has the index 0.
+The device also has a channel called **DoorLockChannel** which contains the functions "set_lock_state" and "async_set_lock_state". These are functions to set the lock state of that device.
+
+If you have a dimmer with multiple I/Os, there are multiple channels. For each I/O a unique channel.
+

docs/api-introduction.md

@@ -0,0 +1,37 @@
+# Batch Testing of Applicable Commands
+
+HomematicIP devices can have different channels, and each channel can have different commands. To test which commands are applicable for a channel, use the `hmip_batch` script. This script will try to execute commands for a device and print the result. It will also print the commands that are not applicable for the device.
+
+The script takes the device ID and the channel index as arguments. You also need a JSON batch file containing the commands.
+
+> **Warning**
+> Please pay close attention to the parameters used for each command. Incorrect or inappropriate parameters may lead to unexpected behavior or even malfunction of your HomematicIP devices. Executing commands is at your own risk. Always double-check the documentation and ensure you understand the effects of each command before using it in your environment.
+
+### Steps to Run a Batch Test
+
+1. Install this library with pip: `pip install -U homematicip`
+2. Get an access token as described above.
+3. Get your device ID and channel index from the device list using:  
+`hmip_cli --list-devices`  
+or dump the configuration with:  
+`hmip_cli --dump-configuration`
+4. Download the JSON batch file from [GitHub](https://github.com/hahn-th/homematicip-rest-api/blob/master/homematicip_demo/hmip_batch.json).
+5. Edit the JSON batch file to choose which commands you want to test. You can enable or disable commands by setting the `active` flag to `true` or `false`.
+
+With the `active` flag you can enable or disable commands:
+
+```json
+{
+  "function": "set_shutter_level_async",
+  "active": false,
+  "params": {
+    "shutter_level": 0.7
+  }
+},
+```
+
+To run the batch test, use the following command:
+
+```sh
+hmip_batch -d <device-id> -i <channel-index> <path-to-json-batch-file>
+```