docs - extended documentation

ReadMe.md

@@ -35,6 +35,10 @@ It's simple. And should also remain so if you have little time for it.
 Send us an email at <a href="mailto:bugs@growautomation.eu">bugs@growautomation.eu</a><br>
 Please check out our <a href="https://docs.growautomation.eu/en/latest/basic/bugs.html">bug guidelines</a> first!
 
+### Support
+Want to support the project?<br>
+<a href="https://www.patreon.com/growautomation">Become a patron</a>
+
 ## Documentation
 <img src="https://readthedocs.org/projects/growautomation/badge/?version=latest&style=plastic"/>
 <a href="https://docs.growautomation.eu">docs.growautomation.eu</a>

docs/source/_static/css/ga.css

@@ -0,0 +1,22 @@
+.ga-img-basic {
+    width: 70%;
+    margin: 5px 0px;
+}
+
+.ga-img-border {
+    border-radius: 5px;
+    border-style: solid;
+    border-color: #343a40;
+    border-width: 3px;
+}
+
+.ga-img-center {
+    display: block;
+    margin-left: auto;
+    margin-right: auto;
+}
+
+.ga-img-right-small {
+    width: 150pt;
+    float: right;
+}

docs/source/basic/bugs.rst

@@ -0,0 +1,70 @@
+.. _basic-bugs:
+
+.. |system_export| image:: ../_static/img/basic/bugs/system_export.png
+   :class: ga-img-basic ga-img-border
+
+====
+Bugs
+====
+
+**When you encounter errors** you can check out our :ref:`troubleshooting guide <basic-troubleshoot>`.
+
+If you could not resolve your problem by troubleshooting you can submit a bug ticket per email.
+
+-----
+
+Support
+*******
+
+The GrowAutomation software is an open source project.
+
+Since we have limited time we cannot operate a basic technical support.
+
+Therefore a community portal will be created to build a knowledge-base: `Community (not yet online) <https://community.growautomation.eu/>`_
+
+**If you want to support our efforts** => consider `becoming a patreon <https://www.patreon.com/growautomation/>`_
+
+-----
+
+Bug hunting
+***********
+
+Before continuing => you need to know what's the source of the error. As described in the :ref:`troubleshooting guide <basic-troubleshoot>`.
+
+Basic
+=====
+
+Note the following in the ticket email:
+
+- What action did you perform as the error occurred? (*if any*)
+- Export the current config and attach it to the email:
+
+  |system_export|
+
+Core
+====
+
+Please prepare the following:
+
+- Set your log-level to 6 or above like described in the :ref:`troubleshooting guide <basic-troubleshoot>`
+- Try to re-create the error
+- Copy the following logs each in a separate text file:
+
+  - core log
+  - growautomation service log
+  - growautomation service journal log
+  - device logs (*if device-logging is enabled and devices are affected*)
+
+- Send a `ticket <mailto:bugs@growautomation.eu>`_
+
+Web
+===
+
+- Try to re-create the error
+- Copy the following logs each in a separate text file:
+
+  - web log
+  - apache-webserver service log
+  - apache-webserver service journal log
+
+- Send a `ticket <mailto:bugs@growautomation.eu>`_

docs/source/basic/intro.rst

@@ -9,6 +9,7 @@ Links
 * `Source on GitHub <https://github.com/superstes/growautomation>`_
 * `Video tutorials <https://www.youtube.com/channel/UCLJyDlo3Z6eP_X2Pw0-Z8Pw>`_
 * `Demo system <https://demo.growautomation.at/>`_
+* `Support the project => Become a patreon <https://www.patreon.com/growautomation/>`_
 
 ----
 
@@ -36,7 +37,6 @@ This project is not
 ===================
 * yet in a stable state
 
-
 ----
 
 Features

docs/source/basic/troubleshoot.rst

@@ -0,0 +1,181 @@
+.. _basic-troubleshoot:
+
+.. |django_error_404| image:: ../_static/img/basic/troubleshoot/django_error_404.png
+   :class: ga-img-basic ga-img-border
+.. |django_error_500| image:: ../_static/img/basic/troubleshoot/django_error_500.png
+   :class: ga-img-basic ga-img-border
+.. |service_failed| image:: ../_static/img/basic/troubleshoot/service_failed.png
+   :class: ga-img-basic ga-img-border
+.. |service_restart| image:: ../_static/img/basic/troubleshoot/service_restart.png
+   :class: ga-img-basic ga-img-border
+.. |log_service| image:: ../_static/img/basic/troubleshoot/log_service.png
+   :class: ga-img-basic ga-img-border
+.. |log_service_journal| image:: ../_static/img/basic/troubleshoot/log_service_journal.png
+   :class: ga-img-basic ga-img-border
+.. |log_app| image:: ../_static/img/basic/troubleshoot/log_app.png
+   :class: ga-img-basic ga-img-border
+.. |log_web| image:: ../_static/img/basic/troubleshoot/log_web.png
+   :class: ga-img-basic ga-img-border
+.. |controller_loglevel| image:: ../_static/img/basic/troubleshoot/controller_loglevel.png
+   :class: ga-img-basic ga-img-border
+.. |system_controller| image:: ../_static/img/basic/troubleshoot/system_controller.png
+   :class: ga-img-basic ga-img-border
+.. |system_service| image:: ../_static/img/basic/troubleshoot/system_service.png
+   :class: ga-img-basic ga-img-border
+.. |system_log| image:: ../_static/img/basic/troubleshoot/system_log.png
+   :class: ga-img-basic ga-img-border
+
+============
+Troubleshoot
+============
+
+Check
+*****
+
+Here's a little checklist of what to check when you run into errors.
+
+
+First
+=====
+
+Check if your configuration meets the requirements as described in this documentation.
+
+The config **WILL NOT** be check for sanity. Only for some common cases.
+
+Therefore errors might occur if the config is not set as expected.
+
+Second
+======
+
+Basic troubleshooting.
+
+You can check out our extended troubleshooting guide mentioned above.
+
+The problem might occur due to one of these components:
+
+- your network
+- the server (*raspberry/linux*)
+- the basic software needed to run GrowAutomation (*database/webserver*)
+- hardware like sensors or wiring
+
+Third
+=====
+
+Check the logs.
+
+Identify
+________
+
+Next you need to identify the source of the error.
+
+It is either the **web-interface** or the **application** itself.
+
+Here are examples of how those errors look like.
+
+Examples
+^^^^^^^^
+
+- **Web-interface**:
+
+  |django_error_404|
+  |django_error_500|
+
+- **Application**:
+
+  - Sensor data is missing
+  - Actions are not performed as expected
+  - The service often/always failing
+
+    |service_failed|
+
+When you identified the source => you can check its logs.
+
+----
+
+Logs
+****
+
+Level
+=====
+
+The main setting regarding logs is the log-level set in the controller settings:
+
+|system_controller|
+
+For troubleshooting you can up this log-level to 6 or above.
+
+But you should revert it back to 1-3 for normal operation.
+
+|controller_loglevel|
+
+After changing it => you must restart the service to activate it.
+
+|service_restart|
+
+View
+====
+
+You can access the logs via the web-interface:
+
+|system_log|
+
+Here you can choose between multiple log types and sub-types.
+
+
+Web
+___
+
+When the error occurred on the web-interface => you can check the web logs for errors.
+
+|log_web|
+
+
+At first you ca
+
+App/Core
+________
+
+When the error occurred in the core application => you can check the core and device logs.
+
+|log_app|
+
+The core service has also
+
+- a **service log**:
+
+  |log_service|
+
+- a **service journal log**:
+
+  |log_service_journal|
+
+
+Device
+______
+
+There is also an option for device-specific logging.
+
+This can be dis-/enabled in the controller settings.
+
+It might help troubleshoot device errors or debugging custom implemented devices.
+
+----
+
+Hardware
+********
+
+Hardware like sensors, actors of any kind and wiring can be troublesome.
+
+There is no generic how-to that will fit any device.
+
+Much of it is just experience with the explicit device.
+
+Therefore we are documenting known issues and their solutions for some of the devices we use:
+
+- :ref:`input device <device-input>`
+- :ref:`output device <device-output>`
+- :ref:`connection device <device-connection>`
+
+We also want to create a clean way of wiring those devices to save troubles.
+
+- :ref:`wiring <device-wiring>`

docs/source/conf.py

@@ -1,9 +1,7 @@
 project = 'GrowAutomation'
-copyright = '2021, René Pascal Rath'
+copyright = '2021, Superstes'
 author = 'René Pascal Rath'
-extensions = [
-    'sphinx_rtd_theme',
-]
+extensions = ['sphinx_rtd_theme']
 templates_path = ['_templates']
 exclude_patterns = []
 html_theme = 'sphinx_rtd_theme'
@@ -12,3 +10,4 @@
 html_logo = '_static/img/ga02c.svg'
 navtree_shift = True
 navtree_root_links = True
+html_css_files = ['css/ga.css']

docs/source/config/dashboard.rst

@@ -1,7 +1,7 @@
 .. _config-dashboard:
 
 .. |element| image:: ../_static/img/config/dashboard/element.svg
-   :width: 50%
+   :class: ga-img-basic ga-img-center
 
 =========
 Dashboard

docs/source/device/connection.rst

@@ -1,14 +1,11 @@
 .. _device-connection:
 
 .. |ads1115| image:: ../_static/img/devices/connection/ads1115.jpg
-   :width: 150pt
-   :class: float-right
+   :class: ga-img-right-small
 .. |mcp3008| image:: ../_static/img/devices/connection/mcp3008.png
-   :width: 150pt
-   :class: float-right
+   :class: ga-img-right-small
 .. |mcp3008_pin| image:: ../_static/img/devices/connection/mcp3008_pinout.png
-   :width: 150pt
-   :class: float-right
+   :class: ga-img-right-small
 
 ==========
 Connection

docs/source/device/input.rst

@@ -1,17 +1,13 @@
 .. _device-input:
 
 .. |soil_moisture_capacitive| image:: ../_static/img/devices/input/soil_humidity_capacitive.png
-   :width: 150pt
-   :class: float-right
+   :class: ga-img-right-small
 .. |soil_moisture_resistance| image:: ../_static/img/devices/input/soil_moisture_resistance.webp
-   :width: 150pt
-   :class: float-right
+   :class: ga-img-right-small
 .. |dht22| image:: ../_static/img/devices/input/dht22.png
-   :width: 150pt
-   :class: float-right
+   :class: ga-img-right-small
 .. |light_photo_resistance| image:: ../_static/img/devices/input/light_sensor_photo_resistance.jpg
-   :width: 150pt
-   :class: float-right
+   :class: ga-img-right-small
 
 =====
 Input
@@ -126,7 +122,7 @@ Dependencies
 Implementation
 --------------
 
-This ia a analogue sensor.
+This ia an analogue sensor.
 
 You need to connect it via a :ref:`connection-device <device-connection>` .
 

docs/source/device/wiring.rst

@@ -0,0 +1,12 @@
+.. _device-wiring:
+
+======
+Wiring
+======
+
+Description
+***********
+How cleanly wire devices.
+
+.. warning::
+   Documentation is not yet finished.