Various changes to documentation framework.

- Reorganize top-level 'doc' Makefile target so submodules can easily
  add their own doc-generating routines to it.  e.g. the Bro project
  makes a placeholder 'doc' target, then adds 'restdoc', 'sphinxdoc';
  later Broccoli can add it's own target as a dependency for generating
  API docs.

- Fixed generated docs for BIFs not being organized under a base/
  subdirectory like the original source files.

- Fixed documentation style for function parameters not applying to
  functions declared as record fields.

- Misc. script documentation tweaks to address warnings given by Sphinx.

testing/btest/Baseline/doc.autogen-reST-func-params/autogen-reST-func-params.rst

@@ -0,0 +1,57 @@
+.. Automatically generated.  Do not edit.
+
+autogen-reST-func-params.bro
+============================
+
+:download:`Original Source File <autogen-reST-func-params.bro>`
+
+Overview
+--------
+
+
+Summary
+~~~~~~~
+Types
+#####
+======================================== =
+:bro:type:`test_rec`: :bro:type:`record`
+======================================== =
+
+Functions
+#########
+===================================== ======================================
+:bro:id:`test_func`: :bro:type:`func` This is a global function declaration.
+===================================== ======================================
+
+Public Interface
+----------------
+Types
+~~~~~
+.. bro:type:: test_rec
+
+   :Type: :bro:type:`record`
+
+      field_func: :bro:type:`function` (i: :bro:type:`int`, j: :bro:type:`int`) : :bro:type:`string`
+         This is a record field function.
+         
+         :param i: First param.
+         :param j: Second param.
+         
+         :returns: A string.
+
+Functions
+~~~~~~~~~
+.. bro:id:: test_func
+
+   :Type: :bro:type:`function` (i: :bro:type:`int`, j: :bro:type:`int`) : :bro:type:`string`
+
+   This is a global function declaration.
+   
+   
+   :param i: First param.
+   
+   :param j: Second param.
+   
+   
+   :returns: A string.
+

testing/btest/doc/autogen-reST-func-params.bro

@@ -0,0 +1,20 @@
+# @TEST-EXEC: bro --doc-scripts %INPUT
+# @TEST-EXEC: btest-diff autogen-reST-func-params.rst
+
+## This is a global function declaration.
+##
+## i: First param.
+## j: Second param.
+##
+## Returns: A string.
+global test_func: function(i: int, j: int): string;
+
+type test_rec: record {
+	## This is a record field function.
+	##
+	## i: First param.
+	## j: Second param.
+	##
+	## Returns: A string.
+	field_func: function(i: int, j: int): string;
+};