Merge pull request #2 from TomerFi/add-docs

Add docs

.dockerignore

@@ -3,6 +3,7 @@
 .git
 .mypy_cache
 .tox
+docs
 shellscripts
 .codecov.yml
 .coverage
@@ -12,6 +13,7 @@ shellscripts
 .prettierignore
 .prettierrc.yml
 bandit.yml
+doc8.ini
 Dockerfile
 Makefile
 mypy.ini

.prettierignore

@@ -1,11 +1,13 @@
-.git
+.git*
+docs*
 .tox*
 .coverage
 .coveragerc
 .dockerignore
 .env_vars
 .gitignore
 .prettierignore
+.shellcheckrc
 Dockerfile
 Makefile
 pylintrc

.shellcheckrc

@@ -0,0 +1,4 @@
+shellscripts/dockerlint-download-prepare.sh
+shellscripts/dockerlint-verify.sh
+shellscripts/push-docker-description.sh
+shellscripts/shellcheck-verify.sh

doc8.ini

@@ -0,0 +1,5 @@
+[doc8]
+allow-long-titles=1
+max-line-length=80
+extension=.rst
+verbose=1

docs/Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

docs/source/conf.py

@@ -0,0 +1,16 @@
+# pylint: disable=invalid-name,redefined-builtin
+
+"""Configuration file for Sphinx Documentation Generator."""
+
+project = 'SwitcherDockerizedWbapi'
+copyright = "2019, Tomer Figenblat"
+author = "Tomer Figenblat"
+templates_path = ['_templates']
+html_theme = 'alabaster'
+html_static_path = ['_static']
+language = 'en'
+
+with open('../../VERSION', 'r') as version_file:
+    version = version_file.readline()
+
+release = version

docs/source/credits.rst

@@ -0,0 +1,16 @@
+Credits
+*******
+
+This project was enabled by creating the aioswitcher_ pypi module,
+initially created for use with the `home assistant component`_.
+
+.. _aioswitcher: https://pypi.org/project/aioswitcher/
+.. _home assistant component: https://www.home-assistant.io/components/switcher_kis
+
+Not this nor the aioswitcher project would have been able to happen without
+the amazing work preformed by NightRang3r and AviadGolan in the
+`Switcher-V2-Python`_ project.
+
+Thank you guys!
+
+.. _Switcher-V2-Python: https://github.com/NightRang3r/Switcher-V2-Python

docs/source/index.rst

@@ -0,0 +1,22 @@
+Welcome to switcher_webapi's documentation!
+===========================================
+
+.. toctree::
+   :maxdepth: 3
+   :caption: Contents:
+
+   what
+   prerequisites
+   notes
+   install
+   usage
+   credits
+   license
+
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`modindex`
+* :ref:`search`

docs/source/install.rst

@@ -0,0 +1,48 @@
+Install
+*******
+
+.. code-block:: shell
+
+   docker run -d -p 8000:8000 \
+   -e CONF_DEVICE_IP_ADDR=192.168.100.157 \
+   -e CONF_PHONE_ID=1234 \
+   -e CONF_DEVICE_ID=ab1c2d \
+   -e CONF_DEVICE_PASSWORD=12345678 \
+   --name switcher_webapi tomerfi/switcher_webapi:latest"
+
+
+You can also add another optional environment variable:
+
+.. code-block:: shell
+
+   -e CONF_THROTTLE=5.0
+
+for setting the throttle time between consecutive requests,
+this is optional and the default value is **5.0**.
+
+Here's an example of running the container using *docker-compose* setting the
+environment variables in a designated file.
+
+.. code-block:: yaml
+
+   # docker-compose.yml
+   version: "3.7"
+
+   services:
+     switcher_api:
+       image: tomerfi/switcher_webapi:latest
+       container_name: "switcher_webapi"
+       env_file:
+         - .env_vars
+       ports:
+         - 8000:8000
+       restart: unless-stopped
+
+.. code-block:: ini
+
+   # .env_vars
+   CONF_DEVICE_IP_ADDR=192.168.100.157
+   CONF_PHONE_ID=1234
+   CONF_DEVICE_ID=ab1c2d
+   CONF_DEVICE_PASSWORD=12345678
+   CONF_THROTTLE=5.0

docs/source/license.rst

@@ -0,0 +1,24 @@
+License
+*******
+
+MIT License
+
+Copyright (c) 2019 Tomer Figenblat
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

docs/source/notes.rst

@@ -0,0 +1,14 @@
+Notes
+*****
+
+.. hlist::
+   :columns: 1
+
+   * If you don't want to be forced to restart the container if the device's ip address changes, please consider assigning the device with a static ip address.
+   * The Switcher-V2-Python repository is build with python 2.7.
+   * The aioswitcher_ was tested with the Switcher V2 device by myself and with the Switcher Touch device by the community.
+   * This project was intended for local usage, it's ok if you want to use it remotely, just make sure to take the proper security measures such as reverse proxy and ssl.
+   * The WebAPI has a throttle mechanism to prevent overfloating the device with frequent requests, it defaults to 5 seconds throttle time.
+   * Some users have been reporting lately about failures using the Switcher-V2-Python script after upgrading the device firmware to 3.0, please follow the relevant issues in the script repository before doing the same.
+
+.. _aioswitcher: https://pypi.org/project/aioswitcher/

docs/source/prerequisites.rst

@@ -0,0 +1,14 @@
+Prerequisites
+*************
+.. hlist::
+   :columns: 1
+
+   * Install and configure your Switcher device.
+   * Collect the following information from the device's following NightRang3r instructions in the `Switcher-V2-Python`_ repository:
+      * ip_address
+      * phone_id
+      * device_id
+      * device_pass
+   * Install docker
+
+.. _Switcher-V2-Python: https://github.com/NightRang3r/Switcher-V2-Python