docs - updating documentation basics

superstes · Nov 28, 2021 · 199e4bc · 199e4bc
1 parent f41439f
commit 199e4bc
Show file tree

Hide file tree

Showing 27 changed files with 128 additions and 358 deletions.
diff --git a/docs/Makefile b/docs/Makefile
diff --git a/docs/html.sh b/docs/html.sh
@@ -0,0 +1,8 @@
+#!/bin/bash
+
+cd "$(dirname "$0")"
+
+rm -rf build
+mkdir build
+
+sphinx-build -b html source/ build/
diff --git a/docs/source/_static/img/basic/bugs/system_export.png b/docs/source/_static/img/basic/bugs/system_export.png
diff --git a/docs/source/basic/bugs.rst b/docs/source/basic/bugs.rst
@@ -3,6 +3,8 @@
 .. |system_export| image:: ../_static/img/basic/bugs/system_export.png
    :class: ga-img-basic ga-img-border
 
+.. include:: ../includes/tip_links.rst
+
 ====
 Bugs
 ====
@@ -37,7 +39,7 @@ 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:
+- Export the current config and attach it to the issue/ticket:
 
   |system_export|
 
@@ -50,21 +52,25 @@ Please prepare the following:
 - 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*)
+  - GrowAutomation - Core
+  - Service - GrowAutomation
+  - Service journal - GrowAutomation
+  - GrowAutomation - DeviceX (*if device-logging is enabled and devices are affected*)
 
-- Send a `ticket <mailto:bugs@growautomation.eu>`_
+- Check if there are `existing issues/bugs <https://github.com/superstes/growautomation/issues>`_
+- Open a new `GitHub issue <https://github.com/superstes/growautomation/issues/new>`_ and attach the logs/config-export to it
 
 Web
 ===
 
+Please prepare the following:
+
 - 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
+  - GrowAutomation - Web
+  - Service - Apache webserver
+  - Service journal - Apache webserver
 
-- Send a `ticket <mailto:bugs@growautomation.eu>`_
+- Check if there are `existing issues/bugs <https://github.com/superstes/growautomation/issues>`_
+- Open a new `GitHub issue <https://github.com/superstes/growautomation/issues/new>`_ and attach the logs/config-export to it
diff --git a/docs/source/basic/intro.rst b/docs/source/basic/intro.rst
@@ -1,41 +1,51 @@
 .. _basic-intro:
 
+
+.. include:: ../includes/tip_links.rst
+
 =====
 Intro
 =====
 
-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/>`_
-
-----
-
 What is GrowAutomation?
 ***********************
 
 Aim of this project
 ===================
-* monitor grow environments
-* start actions based on conditions
-* plant monitoring to analyze success or failure
-* making setup and maintenance easier
+* helping to **optimize grow environments**
+
+  * monitor grow environments using sensors
+  * plant monitoring to analyze success or failure
+  * automating repetitive tasks
+
+    * start actions based on conditions
+
+
+* simplifying **user experience**
 
-  * blueprint for physical setup
+  * providing `a web ui <https://demo.growautomation.eu>`_ for easy maintenance and setup
+  * 'blueprints' for physical setup
   * tutorial videos
-  * passing known issues and their solutions
 
-* extension by external scripts
-* being an independent system
-* create a collection of knowledge regarding this topics
-* building a community around this ideas
+  * collecting knowledge regarding this topics
 
+    * documenting known issues and their solutions
+    * providing systems to support community knowledge-exchange
+
+
+* **customization**
+
+  * support for custom 3th-party scripts
+  * enabling users to customize many system settings to their liking
+  * defaulting to opting-out
+
+
+* being an **independent** system
+
+  * keeping the dependencies to a minimum
+  * possibility to operate as an offline system
+  * preferring opt-out for optional features
 
-This project is not
-===================
-* yet in a stable state
 
 ----
 
@@ -46,14 +56,16 @@ Features
 
   * timed loop to pull data from sensors
 
+
 * output workflow
 
   * support for **complex conditions**
-  * self-reversible actors
+  * self-reversing actors
+
 
 * **web-interface** for user interactions
 
   * configuration management
   * data visualization via **dashboard system**
   * system management
-  * mobile support
+  * smartphone/mobile support
diff --git a/docs/source/basic/troubleshoot.rst b/docs/source/basic/troubleshoot.rst
@@ -25,6 +25,8 @@
 .. |system_log| image:: ../_static/img/basic/troubleshoot/system_log.png
    :class: ga-img-basic ga-img-border
 
+.. include:: ../includes/tip_links.rst
+
 ============
 Troubleshoot
 ============

diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -1,13 +1,17 @@
 project = 'GrowAutomation'
 copyright = '2021, Superstes'
-author = 'René Pascal Rath'
+author = 'Superstes'
 extensions = ['sphinx_rtd_theme']
 templates_path = ['_templates']
 exclude_patterns = []
 html_theme = 'sphinx_rtd_theme'
 html_theme_options = {}
 html_static_path = ['_static']
 html_logo = '_static/img/ga02c.svg'
-navtree_shift = True
-navtree_root_links = True
+# html_favicon = '_static/img/favicon.ico'
 html_css_files = ['css/ga.css']
+master_doc = 'index'
+display_version = True
+# navigation_depth = 4
+# collapse_navigation = True
+sticky_navigation = True
diff --git a/docs/source/config/area.rst b/docs/source/config/area.rst
@@ -1,12 +1,12 @@
 .. _config-area:
 
+.. include:: ../includes/tip_links.rst
+.. include:: ../includes/warn_in_progress.rst
+
 ====
 Area
 ====
 
 Description
 ***********
 How to configure areas to limit actors and/or conditions.
-
-.. warning::
-   Documentation is not yet finished.
diff --git a/docs/source/config/condition.rst b/docs/source/config/condition.rst
@@ -7,6 +7,7 @@
 .. |condition_basic| image:: ../_static/img/config/condition/basic.svg
    :class: ga-img-center-mid
 
+.. include:: ../includes/tip_links.rst
 
 =========
 Condition

diff --git a/docs/source/config/dashboard.rst b/docs/source/config/dashboard.rst
@@ -3,13 +3,13 @@
 .. |element| image:: ../_static/img/config/dashboard/element.svg
    :class: ga-img-basic ga-img-center
 
+.. include:: ../includes/tip_links.rst
+.. include:: ../includes/warn_in_progress.rst
+
 =========
 Dashboard
 =========
 
-.. warning::
-   Documentation is not yet finished.
-
 Description
 ***********
 How to configure dashboards in the GrowAutomation webinterface.

diff --git a/docs/source/config/device.rst b/docs/source/config/device.rst
@@ -1,5 +1,8 @@
 .. _config-device:
 
+.. include:: ../includes/tip_links.rst
+.. include:: ../includes/warn_in_progress.rst
+
 ======
 Device
 ======
@@ -8,9 +11,6 @@ Description
 ***********
 How to configure sensors for the input-workflow.
 
-.. warning::
-   Documentation is not yet finished.
-
 ----
 
 Basic

diff --git a/docs/source/config/script.rst b/docs/source/config/script.rst
@@ -1,12 +1,12 @@
 .. _config-script:
 
+.. include:: ../includes/tip_links.rst
+.. include:: ../includes/warn_in_progress.rst
+
 ======
 Script
 ======
 
 Description
 ***********
 How add and manage custom scripts.
-
-.. warning::
-   Documentation is not yet finished.
diff --git a/docs/source/config/system.rst b/docs/source/config/system.rst
@@ -1,12 +1,12 @@
 .. _config-system:
 
+.. include:: ../includes/tip_links.rst
+.. include:: ../includes/warn_in_progress.rst
+
 ======
 System
 ======
 
 Description
 ***********
 How to configure the controller system.
-
-.. warning::
-   Documentation is not yet finished.
diff --git a/docs/source/config/task.rst b/docs/source/config/task.rst
@@ -1,12 +1,12 @@
 .. _config-task:
 
+.. include:: ../includes/tip_links.rst
+.. include:: ../includes/warn_in_progress.rst
+
 ====
 Task
 ====
 
 Description
 ***********
 How to configure system tasks.
-
-.. warning::
-   Documentation is not yet finished.
diff --git a/docs/source/device/connection.rst b/docs/source/device/connection.rst
@@ -7,11 +7,12 @@
 .. |mcp3008_pin| image:: ../_static/img/devices/connection/mcp3008_pinout.png
    :class: ga-img-right-small
 
+.. include:: ../includes/tip_links.rst
+
 ==========
 Connection
 ==========
 
-
 Description
 ***********
 Here you can find information to the implementation and maintenance of connection-devices such as analog to digital converters.

diff --git a/docs/source/device/input.rst b/docs/source/device/input.rst
@@ -9,6 +9,8 @@
 .. |light_photo_resistance| image:: ../_static/img/devices/input/light_sensor_photo_resistance.jpg
    :class: ga-img-right-small
 
+.. include:: ../includes/tip_links.rst
+
 =====
 Input
 =====

diff --git a/docs/source/device/output.rst b/docs/source/device/output.rst
@@ -5,11 +5,13 @@
 .. |l298n_wiring| image:: ../_static/img/devices/output/l298n_wiring.png
    :class: ga-img-center-mid ga-img-border
 
+.. include:: ../includes/tip_links.rst
+.. include:: ../includes/warn_in_progress.rst
+
 ======
 Output
 ======
 
-
 Description
 ***********
 
@@ -22,9 +24,6 @@ Here you can find information to the implementation and maintenance of output-de
 
    Please include at least the information you see listed in the existing devices below.
 
-.. warning::
-   Documentation is not yet finished.
-
 ----
 
 Devices

diff --git a/docs/source/includes/tip_links.rst b/docs/source/includes/tip_links.rst
@@ -0,0 +1,7 @@
+.. tip::
+    Check out:
+
+    * our `repository on GitHub <https://github.com/superstes/growautomation>`_
+    * our `DEMO system <https://demo.growautomation.eu>`_
+    * our `Video tutorials <https://www.youtube.com/channel/UCLJyDlo3Z6eP_X2Pw0-Z8Pw>`_
+    * our `Patreon page <https://www.patreon.com/growautomation/>`_ => a way of supporting the project
diff --git a/docs/source/includes/warn_in_progress.rst b/docs/source/includes/warn_in_progress.rst
@@ -0,0 +1,2 @@
+.. warning::
+   Documentation is not yet finished.