add more docstrings

diff --git a/logparse/interface.py b/logparse/interface.py
index 90b3ea8e70881dafafc4a0737ff736871ae863c6..bb63f50095c9d2a8f69c1221be43e4a37bf0271b 100644 (file)
--- a/logparse/interface.py
+++ b/logparse/interface.py
@@ -1,12 +1,14 @@
+#!/usr/bin/env python
+# -*- coding: utf-8 -*-
 """
-This module is the entrypoint of the `logparse shell command and also contains
+This module is the entrypoint of the `logparse` shell command and also contains
 single-use functions which don't fit elsewhere. All user interaction with
 logparse should be through this module.
 
 This module provides the following methods:
-    main        Set up arguments, config, logging, and execute parsers
-    rotate      Rotate logs using systemd logrotate
-    rotate_sim  Simulate log rotation
+    - `main()`:         Set up arguments, config, logging, and execute parsers
+    - `rotate()`:       Rotate logs using systemd logrotate
+    - `rotate_sim()`:   Simulate log rotation
 """
 
 import logging, logging.handlers
@@ -28,23 +30,7 @@ def main():
     # Get arguments
 
     global argparser
-    argparser = argparse.ArgumentParser(description='grab logs of some common services and send them by email')
-    argparser.add_argument('-t','--to', help='mail recipient (\"to\" address)', required=False)
-    argparser.add_argument('-c', '--config', help='path to config file', required=False, default="/etc/logparse/logparse.conf")
-    argparser.add_argument('-p', '--print', help='print HTML to stdout', required=False, dest='printout', action='store_true', default=False)
-    argparser.add_argument('-d', '--destination', help='file to output HTML', required=False)
-    argparser.add_argument('-f', '--overwrite', help='force overwrite an existing output file', required=False, action='store_true', default=False)
-    argparser.add_argument('-v', '--verbose', help='verbose console/syslog output (for debugging)', required=False, default=False, action='store_true')
-    argparser.add_argument('-r', '--rotate', help='force rotate log files using systemd logrotate (overrides --rotate and "rotate" in logparse.conf)', required=False, default=False, action='store_true')
-    argparser.add_argument('-nr', '--no-rotate', help='do not rotate logfiles (overrides --rotate and logparse.conf)', required=False, default=False, action='store_true')
-    argparser.add_argument('-s', '--simulate', help="test run logrotate (do not actually change files)", required=False, default=False, action="store_true")
-    argparser.add_argument('-l', '--logs', help='services to analyse', required=False)
-    argparser.add_argument('-nl', '--ignore-logs', help='skip these services (takes precedence over -l)', required=False)
-    argparser.add_argument('-es', '--embed-styles', help='make CSS rules inline rather than linking the file', required=False, default=False, action='store_true')
-    argparser.add_argument('-nh', '--plain', help='write/send plain text rather than HTML', required=False, default=False, action='store_true')
-    argparser.add_argument('-q', '--quiet', help='no output to stdout', required=False, default=False, action='store_true')
-    argparser.add_argument('-nm', '--no-mail', help="do not send email (overrides config file)", required=False, default=False, action="store_true")
-    argparser.add_argument('-nw', '--no-write', help="do not write output file (overrides config file)", required=False, default=False, action="store_true")
+    argparser = get_argparser()
 
     # Load config
 
@@ -176,6 +162,31 @@ def main():
 
     return
 
+def get_argparser():
+    """
+    Initialise arguments (in a separate function for documentation purposes)
+    """
+    argparser = argparse.ArgumentParser(description='grab logs of some common services and send them by email')
+    argparser.add_argument('-t','--to', help='mail recipient (\"to\" address)', required=False)
+    argparser.add_argument('-c', '--config', help='path to config file', required=False, default="/etc/logparse/logparse.conf")
+    argparser.add_argument('-p', '--print', help='print HTML to stdout', required=False, dest='printout', action='store_true', default=False)
+    argparser.add_argument('-d', '--destination', help='file to output HTML', required=False)
+    argparser.add_argument('-f', '--overwrite', help='force overwrite an existing output file', required=False, action='store_true', default=False)
+    argparser.add_argument('-v', '--verbose', help='verbose console/syslog output (for debugging)', required=False, default=False, action='store_true')
+    argparser.add_argument('-r', '--rotate', help='force rotate log files using systemd logrotate (overrides --rotate and "rotate" in logparse.conf)', required=False, default=False, action='store_true')
+    argparser.add_argument('-nr', '--no-rotate', help='do not rotate logfiles (overrides --rotate and logparse.conf)', required=False, default=False, action='store_true')
+    argparser.add_argument('-s', '--simulate', help="test run logrotate (do not actually change files)", required=False, default=False, action="store_true")
+    argparser.add_argument('-l', '--logs', help='services to analyse', required=False)
+    argparser.add_argument('-nl', '--ignore-logs', help='skip these services (takes precedence over -l)', required=False)
+    argparser.add_argument('-es', '--embed-styles', help='make CSS rules inline rather than linking the file', required=False, default=False, action='store_true')
+    argparser.add_argument('-nh', '--plain', help='write/send plain text rather than HTML', required=False, default=False, action='store_true')
+    argparser.add_argument('-q', '--quiet', help='no output to stdout', required=False, default=False, action='store_true')
+    argparser.add_argument('-nm', '--no-mail', help="do not send email (overrides config file)", required=False, default=False, action="store_true")
+    argparser.add_argument('-nw', '--no-write', help="do not write output file (overrides config file)", required=False, default=False, action="store_true")
+    return argparser
+
+
+
 
 def rotate():
     """