played around with sphinx, improved beewatch.server documentation

index.rst

@@ -7,9 +7,13 @@
 Welcome to BeeWatch's documentation!
 ====================================
 
+.. Warning::
+    I do not really care about backwards compatibility.
+    This still is an experimental project and I do not guarantee stability. Actually, I can promise you things will break from time to time.
+
 .. toctree::
-   :maxdepth: 2
+    :maxdepth: 2
-   :caption: Contents:
+    :caption: Contents:
 
 
 

lib/beewatch/server/__init__.py

@@ -33,6 +33,7 @@ import traceback
 import digilib.pin
 import digilib.network
 import beewatch
+# import beewatch.server
 import beewatch.pinapi
 
 log = logging.getLogger(__name__+"")
@@ -41,31 +42,16 @@ log = logging.getLogger(__name__+"")
 lch = logging.getLogger(__name__+".chandler")
 lserver = logging.getLogger(__name__+".server")
 
-class BeeWatchServer(digilib.network.Server):
-    """
-    BeeWatchServer is a subclass of digilib.network.Server. It connects to
-    the gpio control socket and adds protetction by requireing user
-    authentification. This isn't implemented yet.
-    """
-
-    def __init__(self,*args,**kwargs):
-        super(BeeWatchServer, self).__init__(
-            *args,
-            handler_class=beewatch.server.ConnHandlerBeeWatch,
-            **kwargs,
-        )
-
-    def make_socket(self):
-        s = super(BeeWatchServer,self).make_socket()
-        # only for debugging because I'm impatient and don't want to wait
-        lch.warning("setting sokopt SO_REUSEADDR to 1. DEBUGGING ONLY")
-        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
-        return s
 
 class ConnHandlerBeeWatch(digilib.network.ConnHandler):
     """
-    Connection handler for the beewatch server. Applies permission system,
+    ConnHandlerBeeWatch is the connection handler for the BeeWatch server.
-    parses commands and tells apis what to do.
+
+    It parses commands to api calls.
+
+    Todo
+    ----
+        Implement a permission system
     """
     def __init__(self, socket, addr, server):
         super(ConnHandlerBeeWatch, self).__init__(socket, addr, server)
@@ -109,6 +95,48 @@ class ConnHandlerBeeWatch(digilib.network.ConnHandler):
         await self.send(text,log_msg)
 
 
+class BeeWatchServer(digilib.network.Server):
+    """
+    BeeWatchServer opens a secured connection to the outside world (or a file socket).
+
+    BeeWatchServer inherits from digilib.network.Server. It connects to the gpio control socket and adds protetction by requireing user authentification.
+
+    Warning
+    -------
+        as these features aren't implemented yet, the connection is *not* secure at all
+    Todo
+    ----
+        actually implement these features, right now BeeWatchServer does only debug stuff
+
+    Parameters are identical to `digilib.network.Server` if not specified in the following list:
+
+    Parameters
+    ----------
+        *args:
+            passed to :obj:`digilib.network.Server`
+        handler_class:
+            Same as in `digilib.network.Server` but defaults to :obj:`ConnHandlerBeeWatch`.
+        **kwargs:
+            passed to :obj:`digilib.network.Server`
+    """
+    def __init__(
+            self,
+            *args,
+            handler_class=ConnHandlerBeeWatch,
+            **kwargs
+        ):
+        super(BeeWatchServer, self).__init__(
+            *args,
+            handler_class=handler_class,
+            **kwargs,
+        )
+
+    def make_socket(self) -> socket.socket :
+        s = super(BeeWatchServer,self).make_socket()
+        # only for debugging because I'm impatient and don't want to wait
+        lch.warning("setting sokopt SO_REUSEADDR to 1. DEBUGGING ONLY")
+        s.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        return s