docs

6 files changed, 84 insertions, 11 deletions

diff --git a/README b/README
index 7c5f604..cfa23be 100644
--- a/README
+++ b/README
@@ -30,6 +30,8 @@ services and daemons. It is writen in python.
 - procfs
 - iw
 
+The bundled CSS and image files are Twitter Bootstrap.
+
 ### Development
 
 To resolve dependancies on debian-based systems (wheezy or newer?):
@@ -39,5 +41,5 @@ To resolve dependancies on debian-based systems (wheezy or newer?):
 You can run try running the UI on any old Linux machine, just don't submit any
 forms unless you want your network configuration clobbered:
 
-    $ ./torouterui.py
+    $ ./torouterui.py --debug
 
diff --git a/helpers/netif.py b/helpers/netif.py
index 77f710c..529444d 100644
--- a/helpers/netif.py
+++ b/helpers/netif.py
@@ -1,3 +1,7 @@
+"""
+Helper functions for working with network interfaces and network configuration
+(including WiFi).
+"""
 
 import os
 import augeas
@@ -6,7 +10,14 @@ from util import *
 
 def parse_ip(ifname):
     """
-    Example ip link show string:
+    Calls the ``ip`` command and parse the output to collect current status
+    information about a given network interface (specified by ifname argument).
+
+    Returns a dictionary, notably always including a 'state' string value.
+
+    If the interface can not be found at all, raises a KeyError.
+
+    Example ``ip link show`` string:
 
         2: eth0: <BROADCAST,MULTICAST> mtu 1500 qdisc pfifo_fast state DOWN mode DEFAULT qlen 1000
             link/ether 00:12:34:56:78:90 brd ff:ff:ff:ff:ff:ff
@@ -47,6 +58,13 @@ def parse_ip(ifname):
 
 def parse_iw(ifname):
     """
+    Calls the ``iw`` command and parse the output to collect current status
+    information about a given network interface (specified by ifname argument).
+
+    Returns a dictionary, notably always including a 'state' string value.
+
+    If the interface can not be found at all, raises a KeyError.
+
     Example `iw dev wlan0 link` string (sic):
         
         Connected to c0:25:06:51:22:9b (on wlan0)
diff --git a/helpers/sysstatus.py b/helpers/sysstatus.py
index 933f625..99c209b 100644
--- a/helpers/sysstatus.py
+++ b/helpers/sysstatus.py
@@ -1,3 +1,7 @@
+"""
+Helper code for agregating general system status information, and for reading
+in system log files.
+"""
 
 import os
 
@@ -13,6 +17,23 @@ def get_system_status():
     return d
 
 def get_resources_status():
+    """
+    Example ``df -h /home`` output:
+
+        Filesystem              Size  Used Avail Use% Mounted on
+        /dev/mapper/xxxxx-root  231G  184G   35G  85% /
+
+    Example ``free -m`` output:
+
+                    total       used       free     shared    buffers     cached
+        Mem:          3862       2292       1570          0        104        689
+        -/+ buffers/cache:       1498       2364
+        Swap:         7983        202       7781
+
+    Example ``uptime`` output:
+
+         21:38:55 up 7 days,  5:43, 11 users,  load average: 0.60, 0.63, 0.63
+    """
     d = dict()
     disk_info = cli_read_lines('df -h /home')[1].split()
     d['disk_used'] = disk_info[2]
@@ -55,6 +76,15 @@ def get_syslog():
         return None
 
 def get_process_list():
+    """
+    Example ``ps aux`` output:
+
+        USER       PID %CPU %MEM    VSZ   RSS TTY      STAT START   TIME COMMAND
+        root         1  0.0  0.0  10636   676 ?        Ss   Sep08   0:05 init [2]  
+        root         2  0.0  0.0      0     0 ?        S    Sep08   0:00 [kthreadd]
+        root         3  0.0  0.0      0     0 ?        S    Sep08   0:40 [ksoftirqd/0]
+        root         6  0.0  0.0      0     0 ?        S    Sep08   0:00 [migration/0]
+    """
     plist = list()
     first = True
     for l in cli_read_lines('ps aux --sort -%mem')[1:]:
diff --git a/helpers/tor.py b/helpers/tor.py
index 438cb5d..d639ce2 100644
--- a/helpers/tor.py
+++ b/helpers/tor.py
@@ -1,3 +1,7 @@
+"""
+Helper code for interacting with Tor and modifying the Tor system
+configuration.
+"""
 
 def get_tor_status():
     d = dict()
diff --git a/helpers/util.py b/helpers/util.py
index 229d975..dc3b6c0 100644
--- a/helpers/util.py
+++ b/helpers/util.py
@@ -1,3 +1,7 @@
+"""
+Utility functions used by helper code to crudely grab the output of simple UNIX
+command line programs, plus a couple misc other functions.
+"""
 
 import os
 
diff --git a/torouterui.py b/torouterui.py
index 5e8f346..4ef37fb 100755
--- a/torouterui.py
+++ b/torouterui.py
@@ -1,4 +1,18 @@
 #!/usr/bin/env python
+"""
+Main Flask web application code for the torouter user interface.  See also
+README and TODO.
+
+Run ``./torouterui.py --help`` for command line argument options; see bottom of
+this file for that code.
+
+The code that actually interacts with the operating system is the /helpers
+directory.
+
+This code under a BSD license; see LICENSE file included with this code.
+
+<https://trac.torproject.org/projects/tor/wiki/doc/Torouter>
+"""
 
 from flask import Flask, render_template, send_from_directory, request
 import argparse
@@ -7,7 +21,6 @@ import os
 from helpers import sysstatus
 from helpers import netif
 from helpers import tor
-import config
 
 app = Flask(__name__)
 
@@ -23,21 +36,18 @@ def status():
     status['tor'] = tor.get_tor_status()
     return render_template('home.html', settings=None, status=status)
 
-@app.route('/administer/', methods=['GET', 'POST'])
-def administer():
-    return render_template('administer.html', settings=None, status=None)
-
 @app.route('/reboot/', methods=['GET', 'POST'])
 def administer():
+    msg = list()
     if request.method == 'GET':
         return render_template('reboot.html', status=None)
     elif request.form.has_key('confirm'):
-        # XXX: execute reboot
+        # TODO: actually execute reboot
+        #os.system('reboot &')
         return render_template('reboot.html', status='rebooting')
     else:
-        # XXX: flashing introduces cookies
-        #flash("Didn't confirm, not rebooting", "warning")
-        return render_template('reboot.html', status=None)
+        msg.append(("error", "Didn't confirm, not rebooting",),)
+        return render_template('reboot.html', status=None, messages=msg)
 
 @app.route('/wan/', methods=['GET', 'POST'])
 def wan():
@@ -177,6 +187,7 @@ def wifi():
 
 @app.route('/tor/', methods=['GET', 'POST'])
 def torpage():
+    # TODO: unimplemented
     msg = list()
     return render_template('tor.html', settings=None, status=None,
         form=request.form, formerr=None, messages=msg)
@@ -196,16 +207,20 @@ def processes():
 
 @app.route('/favicon.ico')
 def favicon():
+    """ Simple static redirect """
     return send_from_directory(os.path.join(app.root_path, 'static'),
                                'favicon.ico',
                                mimetype='image/vnd.microsoft.icon')
 
 @app.route('/robots.txt')
 def robots():
+    """ "Just in case?" """
     return send_from_directory(os.path.join(app.root_path, 'static'),
                                'robots.txt',
                                mimetype='text/plain')
 
+##############################################################################
+
 if __name__ == '__main__':
     parser = argparse.ArgumentParser()
     parser.add_argument('--debug', action='store_true',