add documentation to tsstats.{config,log,template,utils}.*

docs/source/api.rst

@@ -1,6 +1,12 @@
 API
 ***
 
+Log
+===
+
+.. automodule:: tsstats.log
+  :members:
+
 Client
 ======
 .. autoclass:: tsstats.client.Client
@@ -14,7 +20,25 @@ Client
   .. automethod:: tsstats.client.Clients.__init__
   .. automethod:: tsstats.client.Clients.__iter__
 
+Template
+========
+
+.. automodule:: tsstats.template
+  :members:
+
+Config
+======
+
+.. automodule:: tsstats.config
+  :members:
+
 Exceptions
 ==========
 .. automodule:: tsstats.exceptions
   :members:
+
+Utils
+=====
+
+.. automodule:: tsstats.utils
+  :members:

docs/source/conf.py

@@ -56,7 +56,7 @@ author = 'Thor77'
 # The short X.Y version.
 version = '0.5'
 # The full version, including alpha/beta/rc tags.
-release = '0.5.5'
+release = '0.5.6'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

setup.py

@@ -2,7 +2,7 @@ from setuptools import setup
 
 setup(
     name='tsstats',
-    version='0.5.5',
+    version='0.5.6',
     author='Thor77',
     author_email='thor77@thor77.org',
     description='A simple Teamspeak stats-generator',

tsstats/config.py

@@ -9,6 +9,15 @@ logger = logging.getLogger('tsstats')
 
 
 def parse_config(config_path):
+    '''
+    parse config at `config_path`
+
+    :param config_path: path to config-file
+    :type config_path: str
+
+    :return: values of config
+    :rtype: tuple
+    '''
     logger.debug('reading config')
     config = ConfigParser()
     config.read(config_path)

tsstats/log.py

@@ -20,6 +20,18 @@ logger = logging.getLogger('tsstats')
 
 
 def parse_logs(log_glob, ident_map=None):
+    '''
+    parse logs specified by globbing pattern `log_glob`
+
+    :param log_glob: path to log-files (supports globbing)
+    :param ident_map: :ref:`IdentMap`
+
+    :type log_glob: str
+    :type ident_map: dict
+
+    :return: parsed clients
+    :rtype: tsstats.client.Clients
+    '''
     clients = Clients(ident_map)
     for log_file in sorted(log_file for log_file in glob(log_glob)):
         clients = parse_log(log_file, ident_map, clients)
@@ -27,6 +39,20 @@ def parse_logs(log_glob, ident_map=None):
 
 
 def parse_log(log_path, ident_map=None, clients=None):
+    '''
+    parse log-file at `log_path`
+
+    :param log_path: path to log-file
+    :param ident_map: :ref:`IdentMap`
+    :param clients: clients-object to add parsing-results to
+
+    :type log_path: str
+    :type ident_map: dict
+    :type clients: tsstats.client.Clients
+
+    :return: parsed clients
+    :rtype: tsstats.client.Clients
+    '''
     if not clients:
         clients = Clients(ident_map)
     log_file = open(log_path)

tsstats/template.py

@@ -11,6 +11,19 @@ logger = logging.getLogger('tsstats')
 
 def render_template(clients, output, template_name='tsstats/template.html',
                     title='TeamspeakStats'):
+    '''
+    render template with `clients`
+
+    :param clients: clients to fill template with
+    :param output: path to output-file
+    :param template_name: path to template-file
+    :param title: title of the resulting html-document
+
+    :type clients: tsstats.client.Clients
+    :type output: str
+    :type template_name: str
+    :type title: str
+    '''
     # prepare clients
     clients_onlinetime_ = sort_clients(clients, 'onlinetime')
     clients_onlinetime = [

tsstats/utils.py

@@ -1,9 +1,30 @@
 def sort_clients(clients, key):
+    '''
+    sort `clients` by `key`
+
+    :param clients: clients to sort
+    :param key: key to sort clients with
+
+    :type clients: tsstats.client.Clients
+    :type key: str
+
+    :return: sorted `clients`
+    :rtype: list
+    '''
     cl_data = [(client, client[key]) for client in clients if client[key] > 0]
     return sorted(cl_data, key=lambda data: data[1], reverse=True)
 
 
 def seconds_to_text(seconds):
+    '''
+    convert `seconds` to a text-representation
+
+    :param seconds: seconds to convert
+    :type seconds: int
+
+    :return: `seconds` as text-representation
+    :rtype: str
+    '''
     minutes, seconds = divmod(seconds, 60)
     hours, minutes = divmod(minutes, 60)
     hours = str(hours) + 'h ' if hours > 0 else ''