Improving documention for the Bro script document-generation process

Some minor organizational revisions to the python scripting.

doc/scripts/generate_reST_docs.py.in

@@ -6,102 +6,12 @@ import shutil
 import glob
 import string
 import sys
+from BroToReST import *
 
-BRO = "@CMAKE_BINARY_DIR@/src/bro"
-BROPATHDEV = "`@CMAKE_BINARY_DIR@/bro-path-dev`"
-BRO_ARGS = "--doc-scripts"
-DOC_DST_DIR = "@DOC_SOURCE_WORKDIR@/policy"
-BROPATH = subprocess.Popen("@CMAKE_BINARY_DIR@/bro-path-dev", shell=True,
-        stdout=subprocess.PIPE, stderr=subprocess.STDOUT).stdout.readline()
-
-class BroToReST:
-    bro_src_file = None
-    doc_src_file = None
-    load_via_stdin = False
-    group = None
-
-    def __init__(self, src_file, load_method=False, search_dir=None, group=None):
-        self.bro_src_file = FindBroScript(src_file, search_dir)
-        self.load_via_stdin = load_method
-        self.group = group
-
-        # formulate doc_src_file from src_file
-        filename = os.path.basename(src_file)
-        basename, ext = os.path.splitext(filename)
-        if ext == ".bro":
-            self.doc_src_file = basename + ".rst"
-        else:
-            self.doc_src_file = filename + ".rst"
-
-    def __str__(self):
-        return "bro_src_file: " + self.bro_src_file \
-           + "\ndoc_src_file: " + self.doc_src_file \
-           + "\ndoc_dst_file: " + os.path.join(DOC_DST_DIR, self.doc_src_file) \
-           + "\nstdin_load: %s" % self.load_via_stdin \
-           + "\ngroup: %s" % self.group
-
-    def GenDoc(self):
-        bro_src_basename = os.path.basename(self.bro_src_file)
-
-        if self.load_via_stdin:
-            cmd = "echo '@load %s' | %s %s" % (bro_src_basename, BRO, BRO_ARGS)
-        else:
-            cmd = "%s %s %s" % (BRO, BRO_ARGS, self.bro_src_file)
-
-        p = subprocess.Popen(cmd, shell=True, env={"BROPATH": BROPATH})
-
-        if p.wait() == 0:
-            shutil.copy(self.doc_src_file, DOC_DST_DIR)
-            shutil.copy(self.bro_src_file, DOC_DST_DIR)
-            AppendToDocGroup(self.group, self.bro_src_file, self.doc_src_file)
-
-        for leftover in glob.glob("*.rst"):
-            os.remove(leftover)
-
-def GenDocs(doc_dict, load_method=False):
-    for k, v in doc_dict.iteritems():
-        doc = BroToReST(k, load_method, group=v)
-        print "Generating reST document for " + k
-        doc.GenDoc()
-
-# search BROPATH for the script and return the absolute path to it
-def FindBroScript(src_file, search_dir=None):
-    if search_dir is None:
-        search_dir = string.split(BROPATH, ":")
-    for path in search_dir:
-        abs_path = os.path.join(path, src_file)
-        if os.path.exists(abs_path):
-            return abs_path
-    print >> sys.stderr, "Couldn't find '%s'" % src_file
-    return None
-
-def AppendToDocGroup(group, src_file, doc_file):
-    if group is None:
-        return
-
-    group_file = os.path.join(DOC_DST_DIR, group + ".rst")
-    if not os.path.exists(group_file):
-        print >> sys.stderr, "Group file doesn't exist: " + group_file
-        return
-
-    summary_comments = []
-
-    with open(src_file, 'r') as f:
-        for line in f:
-            sum_pos = string.find(line, "##!")
-            if sum_pos != -1:
-                summary_comments.append(line[(sum_pos+3):])
-
-    doc_name, ext = os.path.splitext(doc_file)
-
-    with open(group_file, 'a') as f:
-        f.write("\n:doc:`%s`\n" % doc_name)
-        for line in summary_comments:
-            f.write(line)
-
-# Scripts that can be loaded by bro via command line argument
 # TODO: generate docs for more scripts
 # TODO: the groups are just made up to test the functionality, fix them
+
+# Scripts that can be loaded by bro via command line argument:
 docs = {
     "alarm.bro":        "internal",
     "arp.bro":          "user",
@@ -124,7 +34,7 @@ docs = {
 }
 
 # Scripts that can't be loaded by bro via command line argument (possible
-# due to dependency issues), but can be loaded via an @load on stdin
+# due to dependency issues), but can be loaded via an @load on stdin:
 stdin_docs = {
     "notice.bro": "internal",
 }
@@ -132,9 +42,11 @@ stdin_docs = {
 GenDocs(docs)
 GenDocs(stdin_docs, True)
 
+# The example documentation script doesn't live on the BROPATH, so
+# explicitly generate the docs for it like this:
 BroToReST("example.bro", False, ["@PROJECT_SOURCE_DIR@/doc"], group="internal").GenDoc()
 
-# Generate documentation for stuff that's always loaded into bro by default
+# Generate documentation for stuff that's always loaded into bro by default:
 cmd = "echo '' | %s %s" % (BRO, BRO_ARGS)
 p = subprocess.Popen(cmd, shell=True, env={"BROPATH": BROPATH})
 if p.wait() == 0: