Move stuff related to policy script documentation from doc/ to doc/scripts/

doc/scripts/source/_static/showhide.js

@@ -0,0 +1,64 @@
+// make literal blocks corresponding to identifier initial values
+// hidden by default
+$(document).ready(function() {
+
+    var showText='(Show Value)';
+    var hideText='(Hide Value)';
+
+    var is_visible = false;
+
+    // select field-list tables that come before a literal block
+    tables = $('.highlight-python').prev('table.docutils.field-list');
+
+    tables.find('th.field-name').filter(function(index) {
+        return $(this).html() == "Default :";
+    }).next().append('<a href="#" class="toggleLink">'+showText+'</a>');
+
+    // hide all literal blocks that follow a field-list table
+    tables.next('.highlight-python').hide();
+
+    // register handler for clicking a "toggle" link
+    $('a.toggleLink').click(function() {
+        is_visible = !is_visible;
+
+        $(this).html( (!is_visible) ? showText : hideText);
+
+        // the link is inside a <table><tbody><tr><td> and the next
+        // literal block after the table is the literal block that we want
+        // to show/hide
+        $(this).parent().parent().parent().parent().next('.highlight-python').slideToggle('fast');
+
+        // override default link behavior
+        return false;
+    });
+});
+
+// make "Private Interface" sections hidden by default
+$(document).ready(function() {
+
+    var showText='Show Private Interface (for internal use)';
+    var hideText='Hide Private Interface';
+
+    var is_visible = false;
+
+    // insert show/hide links
+    $('#private-interface').children(":first-child").after('<a href="#" class="privateToggle">'+showText+'</a>');
+
+    // wrap all sub-sections in a new div that can be hidden/shown
+    $('#private-interface').children(".section").wrapAll('<div class="private" />');
+
+    // hide the given class
+    $('.private').hide();
+
+    // register handler for clicking a "toggle" link
+    $('a.privateToggle').click(function() {
+        is_visible = !is_visible;
+
+        $(this).html( (!is_visible) ? showText : hideText);
+
+        $('.private').slideToggle('fast');
+
+        // override default link behavior
+        return false;
+    });
+});

doc/scripts/source/_templates/layout.html

@@ -0,0 +1,5 @@
+{% extends "!layout.html" %}
+{% block extrahead %}
+    <script type="text/javascript" src="{{ pathto('_static/showhide.js', 1) }}"></script>
+    {{ super() }}
+{% endblock %}

doc/scripts/source/builtins.rst

@@ -0,0 +1,121 @@
+Builtin Types and Attributes
+============================
+
+Types
+-----
+
+The Bro scripting language supports the following built-in types.
+
+.. TODO: add documentation
+
+.. bro:type:: void
+
+.. bro:type:: bool
+
+.. bro:type:: int
+
+.. bro:type:: count
+
+.. bro:type:: counter
+
+.. bro:type:: double
+
+.. bro:type:: time
+
+.. bro:type:: interval
+
+.. bro:type:: string
+
+.. bro:type:: pattern
+
+.. bro:type:: enum
+
+.. bro:type:: timer
+
+.. bro:type:: port
+
+.. bro:type:: addr
+
+.. bro:type:: net
+
+.. bro:type:: subnet
+
+.. bro:type:: any
+
+.. bro:type:: table
+
+.. bro:type:: union
+
+.. bro:type:: record
+
+.. bro:type:: types
+
+.. bro:type:: func
+
+.. bro:type:: file
+
+.. bro:type:: vector
+
+.. TODO: below are kind of "special cases" that bro knows about?
+
+.. bro:type:: set
+
+.. bro:type:: function
+
+.. bro:type:: event
+
+.. TODO: Notice will get documented as part of notice.bro, which can eventually
+   be referenced here once that documentation is auto-generated.
+
+.. bro:type:: Notice
+
+Attributes
+----------
+
+The Bro scripting language supports the following built-in attributes.
+
+.. TODO: add documentation
+
+.. bro:attr:: &optional
+
+.. bro:attr:: &default
+
+.. bro:attr:: &redef
+
+.. bro:attr:: &rotate_interval
+
+.. bro:attr:: &rotate_size
+
+.. bro:attr:: &add_func
+
+.. bro:attr:: &delete_func
+
+.. bro:attr:: &expire_func
+
+.. bro:attr:: &read_expire
+
+.. bro:attr:: &write_expire
+
+.. bro:attr:: &create_expire
+
+.. bro:attr:: &persistent
+
+.. bro:attr:: &synchronized
+
+.. bro:attr:: &postprocessor
+
+.. bro:attr:: &encrypt
+
+.. bro:attr:: &match
+
+.. bro:attr:: &disable_print_hook
+
+.. bro:attr:: &raw_output
+
+.. bro:attr:: &mergeable
+
+.. bro:attr:: &priority
+
+.. bro:attr:: &group
+
+.. bro:attr:: (&tracked)

doc/scripts/source/common.rst

@@ -0,0 +1,19 @@
+Common Documentation
+====================
+
+.. _common_port_analysis_doc:
+
+Port Analysis
+-------------
+
+TODO: add some stuff here
+
+.. _common_packet_filter_doc:
+
+Packet Filter
+-------------
+
+TODO: add some stuff here
+
+.. note:: Filters are only relevant when dynamic protocol detection (DPD)
+          is explicitly turned off (Bro release 1.6 enabled DPD by default).

doc/scripts/source/ext/bro.py

@@ -0,0 +1,167 @@
+"""
+    The Bro domain for Sphinx.
+"""
+
+def setup(Sphinx):
+    Sphinx.add_domain(BroDomain)
+
+from sphinx import addnodes
+from sphinx.domains import Domain, ObjType, Index
+from sphinx.locale import l_, _
+from sphinx.directives import ObjectDescription
+from sphinx.roles import XRefRole
+from sphinx.util.nodes import make_refnode
+import string
+
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from docutils.parsers.rst import directives
+from docutils.parsers.rst.roles import set_classes
+
+class BroGeneric(ObjectDescription):
+    def add_target_and_index(self, name, sig, signode):
+        targetname = self.objtype + '-' + name
+        if targetname not in self.state.document.ids:
+            signode['names'].append(targetname)
+            signode['ids'].append(targetname)
+            signode['first'] = (not self.names)
+            self.state.document.note_explicit_target(signode)
+
+            objects = self.env.domaindata['bro']['objects']
+            key = (self.objtype, name)
+# this is commented out mostly just to avoid having a special directive
+# for events in order to avoid the duplicate warnings in that case
+            """
+            if key in objects:
+                self.env.warn(self.env.docname,
+                              'duplicate description of %s %s, ' %
+                              (self.objtype, name) +
+                              'other instance in ' +
+                              self.env.doc2path(objects[key]),
+                              self.lineno)
+            """
+            objects[key] = self.env.docname
+        indextext = self.get_index_text(self.objtype, name)
+        if indextext:
+            self.indexnode['entries'].append(('single', indextext,
+                                              targetname, targetname))
+
+    def get_index_text(self, objectname, name):
+        return _('%s (%s)') % (name, self.objtype)
+
+    def handle_signature(self, sig, signode):
+        signode += addnodes.desc_name("", sig)
+        return sig
+
+class BroNamespace(BroGeneric):
+    def add_target_and_index(self, name, sig, signode):
+        targetname = self.objtype + '-' + name
+        if targetname not in self.state.document.ids:
+            signode['names'].append(targetname)
+            signode['ids'].append(targetname)
+            signode['first'] = (not self.names)
+            self.state.document.note_explicit_target(signode)
+
+            objects = self.env.domaindata['bro']['objects']
+            key = (self.objtype, name)
+            objects[key] = self.env.docname
+        indextext = self.get_index_text(self.objtype, name)
+        self.indexnode['entries'].append(('single', indextext,
+                                          targetname, targetname))
+        self.indexnode['entries'].append(('single',
+                                          "namespaces; %s" % (sig),
+                                          targetname, targetname))
+
+    def get_index_text(self, objectname, name):
+        return _('%s (namespace); %s') % (name, self.env.docname)
+
+    def handle_signature(self, sig, signode):
+        signode += addnodes.desc_name("", sig)
+        return sig
+
+class BroEnum(BroGeneric):
+    def add_target_and_index(self, name, sig, signode):
+        targetname = self.objtype + '-' + name
+        if targetname not in self.state.document.ids:
+            signode['names'].append(targetname)
+            signode['ids'].append(targetname)
+            signode['first'] = (not self.names)
+            self.state.document.note_explicit_target(signode)
+
+            objects = self.env.domaindata['bro']['objects']
+            key = (self.objtype, name)
+            objects[key] = self.env.docname
+        indextext = self.get_index_text(self.objtype, name)
+        #self.indexnode['entries'].append(('single', indextext,
+        #                                  targetname, targetname))
+        m = sig.split()
+        self.indexnode['entries'].append(('single',
+                                          "%s (enum values); %s" % (m[1], m[0]),
+                                          targetname, targetname))
+
+    def handle_signature(self, sig, signode):
+        m = sig.split()
+        name = m[0]
+        signode += addnodes.desc_name("", name)
+        return name
+
+class BroIdentifier(BroGeneric):
+    def get_index_text(self, objectname, name):
+        return name
+
+class BroAttribute(BroGeneric):
+    def get_index_text(self, objectname, name):
+        return _('%s (attribute)') % (name)
+
+class BroDomain(Domain):
+    """Bro domain."""
+    name = 'bro'
+    label = 'Bro'
+
+    object_types = {
+        'type':             ObjType(l_('type'),             'type'),
+        'namespace':        ObjType(l_('namespace'),        'namespace'),
+        'id':               ObjType(l_('id'),               'id'),
+        'enum':             ObjType(l_('enum'),             'enum'),
+        'attr':             ObjType(l_('attr'),             'attr'),
+    }
+
+    directives = {
+        'type':             BroGeneric,
+        'namespace':        BroNamespace,
+        'id':               BroIdentifier,
+        'enum':             BroEnum,
+        'attr':             BroAttribute,
+    }
+
+    roles = {
+        'type':             XRefRole(),
+        'namespace':        XRefRole(),
+        'id':               XRefRole(),
+        'enum':             XRefRole(),
+        'attr':             XRefRole(),
+    }
+
+    initial_data = {
+        'objects': {},  # fullname -> docname, objtype
+    }
+
+    def clear_doc(self, docname):
+        for (typ, name), doc in self.data['objects'].items():
+            if doc == docname:
+                del self.data['objects'][typ, name]
+
+    def resolve_xref(self, env, fromdocname, builder, typ, target, node,
+                     contnode):
+        objects = self.data['objects']
+        objtypes = self.objtypes_for_role(typ)
+        for objtype in objtypes:
+            if (objtype, target) in objects:
+                return make_refnode(builder, fromdocname,
+                                    objects[objtype, target],
+                                    objtype + '-' + target,
+                                    contnode, target + ' ' + objtype)
+
+    def get_objects(self):
+        for (typ, name), docname in self.data['objects'].iteritems():
+            yield name, name, typ, docname, typ + '-' + name, 1

doc/scripts/source/index.rst

@@ -0,0 +1,24 @@
+.. Bro documentation master file
+
+Welcome to Bro's documentation!
+===============================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   common
+   builtins
+   policy/default
+   policy/user
+   policy/bifs
+   policy/internal
+   policy/index
+
+Indices and tables
+==================
+
+* :ref:`genindex`
+* :ref:`search`

doc/scripts/source/policy/bifs.rst

@@ -0,0 +1,4 @@
+Built-In Functions (BIFs)
+=========================
+
+Here's a list of all documentation for BIFs that Bro provides:

doc/scripts/source/policy/default.rst

@@ -0,0 +1,3 @@
+Bro Scripts Loaded by Default
+=============================
+

doc/scripts/source/policy/index.rst

@@ -0,0 +1,10 @@
+Index of All Policy Script Documentation
+========================================
+
+Contents:
+
+.. toctree::
+   :maxdepth: 1
+   :glob:
+
+   *

doc/scripts/source/policy/internal.rst

@@ -0,0 +1,3 @@
+Internal Policy Scripts
+=======================
+

doc/scripts/source/policy/user.rst

@@ -0,0 +1,3 @@
+User-Facing Policy Scripts
+==========================
+