Update the generated script doc organization.

Added an additional master TOC index for Bro script packages that
automatically gets filled in at ``make doc`` time.  The master TOC
links to per-package indexes which contains links to all the scripts
contained within it along with their summary.  The per-package index
is also now automatically generated/derived from the path component
of the script passed into the rest_target() macro.

doc/scripts/CMakeLists.txt

@@ -1,4 +1,3 @@
-set(POLICY_SRC_DIR ${PROJECT_SOURCE_DIR}/policy)
 set(BIF_SRC_DIR ${PROJECT_SOURCE_DIR}/src)
 set(RST_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/rest_output)
 set(DOC_OUTPUT_DIR ${CMAKE_CURRENT_BINARY_DIR}/out)
@@ -28,8 +27,12 @@ endif ()
 #     rest_target(srcDir broInput [group])
 #
 # srcDir: the directory which contains broInput
-# broInput: the file name of a bro policy script
+# broInput: the file name of a bro policy script, any path prefix of this
-# group: optional name of group that the script documentation will belong to
+#     argument will be used to derive what path under policy/ the generated
+#     documentation will be placed.
+# group: optional name of group that the script documentation will belong to.
+#     If this is not given, .bif files automatically get their own group or
+#     the group is automatically by any path portion of the broInput argument.
 #
 # In addition to adding the makefile target, several CMake variables are set:
 #
@@ -39,24 +42,25 @@ endif ()
 # ALL_REST_OUTPUTS: a running list (the CMake list type) of all reST docs
 #   that are to be generated
 # MASTER_GROUP_LIST: a running list (the CMake list type) of all script groups
+# MASTER_PKG_LIST: a running list (the CMake list type) of all script groups
+#   that were defived from the path portion of the broInput argument
 # ${group}_files: a running list of files belonging to a given group, from
 #   which summary text can be extracted at build time
 # ${group}_doc_names: a running list of reST style document names that can be
 #   given to a :doc: role, shared indices with ${group}_files
 #
 macro(REST_TARGET srcDir broInput)
-    get_filename_component(basename ${broInput} NAME_WE)
+    set(absSrcPath ${srcDir}/${broInput})
+    get_filename_component(basename ${broInput} NAME)
+    string(REPLACE .bro "" basename ${basename})
     get_filename_component(extension ${broInput} EXT)
     get_filename_component(relDstDir ${broInput} PATH)
 
-    set(sumTextSrc ${srcDir}/${broInput})
+    set(sumTextSrc ${absSrcPath})
     if (${extension} STREQUAL ".bif.bro")
-        set(basename "${basename}.bif")
         # the summary text is taken at configure time, but .bif.bro files
         # may not have been generated yet, so read .bif file instead
         set(sumTextSrc ${BIF_SRC_DIR}/${basename})
-    elseif (${extension} STREQUAL ".init")
-        set(basename "${basename}.init")
     endif ()
 
     if (NOT relDstDir)
@@ -71,12 +75,27 @@ macro(REST_TARGET srcDir broInput)
     string(REPLACE "/" "^" restFile ${restFile})
     set(restOutput "${dstDir}/${basename}.rst")
 
-    set(indexEntry "   ${docName} <${docName}>")
+    set(MASTER_POLICY_INDEX_TEXT
-    set(MASTER_POLICY_INDEX_TEXT "${MASTER_POLICY_INDEX_TEXT}\n${indexEntry}")
+        "${MASTER_POLICY_INDEX_TEXT}\n   ${docName} <${docName}>")
     list(APPEND ALL_REST_OUTPUTS ${restOutput})
 
     if (NOT "${ARGN}" STREQUAL "")
         set(group ${ARGN})
+    elseif (${extension} STREQUAL ".bif.bro")
+        set(group bifs)
+    elseif (relDstDir)
+        set(pkgIndex policy/${relDstDir}/index)
+        set(group ${pkgIndex})
+        # add package index to master package list if not already in it
+        list(FIND MASTER_PKG_LIST ${pkgIndex} _found)
+        if (_found EQUAL -1)
+            list(APPEND MASTER_PKG_LIST ${pkgIndex})
+        endif ()
+    else ()
+        set(group "")
+    endif ()
+
+    if (NOT "${group}" STREQUAL "")
         # add group to master group list if not already in it
         list(FIND MASTER_GROUP_LIST ${group} _found)
         if (_found EQUAL -1)
@@ -90,14 +109,6 @@ macro(REST_TARGET srcDir broInput)
 
         list(APPEND ${group}_files ${sumTextSrc})
         list(APPEND ${group}_doc_names ${docName})
-    else ()
-        set(group "")
-    endif ()
-
-    if ("${group}" STREQUAL "default" OR "${group}" STREQUAL "bifs")
-        set(BRO_ARGS --doc-scripts --exec '')
-    else ()
-        set(BRO_ARGS --doc-scripts ${broInput})
     endif ()
 
     add_custom_command(OUTPUT ${restOutput}
@@ -106,7 +117,7 @@ macro(REST_TARGET srcDir broInput)
         ARGS -E remove_directory .state
         # generate the reST documentation using bro
         COMMAND BROPATH=${BROPATH}:${srcDir} ${CMAKE_BINARY_DIR}/src/bro
-        ARGS ${BRO_ARGS} || (rm -rf .state *.log *.rst && exit 1)
+        ARGS --doc-scripts ${broInput} || (rm -rf .state *.log *.rst && exit 1)
         # move generated doc into a new directory tree that
         # defines the final structure of documents
         COMMAND "${CMAKE_COMMAND}"
@@ -115,143 +126,34 @@ macro(REST_TARGET srcDir broInput)
         ARGS -E copy ${restFile} ${restOutput}
         # copy the bro policy script, too
         COMMAND "${CMAKE_COMMAND}"
-        ARGS -E copy ${srcDir}/${broInput} ${dstDir}
+        ARGS -E copy ${absSrcPath} ${dstDir}
         # clean up the build directory
         COMMAND rm
         ARGS -rf .state *.log *.rst
         DEPENDS bro
-        DEPENDS ${srcDir}/${broInput}
+        DEPENDS ${absSrcPath}
         COMMENT "[Bro] Generating reST docs for ${broInput}"
     )
 
 endmacro(REST_TARGET)
 
 # Schedule Bro scripts for which to generate documentation.
-#
+include(DocSourcesList.cmake)
-# Note: any path prefix of the script (2nd argument of rest_target macro)
-# will be used to derive what path under policy/ the generated documentation
-# will be placed.
-
-rest_target(${CMAKE_CURRENT_SOURCE_DIR} example.bro)
-
-rest_target(${CMAKE_BINARY_DIR}/src bro.bif.bro)
-rest_target(${CMAKE_BINARY_DIR}/src const.bif.bro)
-rest_target(${CMAKE_BINARY_DIR}/src event.bif.bro)
-rest_target(${CMAKE_BINARY_DIR}/src logging.bif.bro)
-rest_target(${CMAKE_BINARY_DIR}/src strings.bif.bro)
-rest_target(${CMAKE_BINARY_DIR}/src types.bif.bro)
-
-set(psd ${POLICY_SRC_DIR})
-
-rest_target(${psd} bro.init)
-rest_target(${psd} site.bro)
-
-rest_target(${psd} detectors/http-MHR.bro)
-
-rest_target(${psd} frameworks/communication/base.bro)
-rest_target(${psd} frameworks/communication/listen-clear.bro)
-rest_target(${psd} frameworks/communication/listen-ssl.bro)
-
-rest_target(${psd} frameworks/dpd/base.bro)
-rest_target(${psd} frameworks/dpd/dyn-disable.bro)
-rest_target(${psd} frameworks/dpd/packet-segment-logging.bro)
-
-rest_target(${psd} frameworks/intel/base.bro)
-
-rest_target(${psd} frameworks/logging/base.bro)
-rest_target(${psd} frameworks/logging/plugins/ascii.bro)
-
-rest_target(${psd} frameworks/metrics/base.bro)
-rest_target(${psd} frameworks/metrics/conn-example.bro)
-rest_target(${psd} frameworks/metrics/http-example.bro)
-
-rest_target(${psd} frameworks/notice/action-filters.bro)
-rest_target(${psd} frameworks/notice/base.bro)
-rest_target(${psd} frameworks/notice/weird.bro)
-
-rest_target(${psd} frameworks/packet-filter/base.bro)
-rest_target(${psd} frameworks/packet-filter/netstats.bro)
-
-rest_target(${psd} frameworks/signatures/base.bro)
-
-rest_target(${psd} frameworks/software/base.bro)
-rest_target(${psd} frameworks/software/vulnerable.bro)
-
-rest_target(${psd} integration/barnyard2/base.bro)
-rest_target(${psd} integration/barnyard2/event.bro)
-rest_target(${psd} integration/barnyard2/types.bro)
-
-rest_target(${psd} protocols/conn/base.bro)
-rest_target(${psd} protocols/conn/contents.bro)
-rest_target(${psd} protocols/conn/inactivity.bro)
-rest_target(${psd} protocols/conn/known-hosts.bro)
-rest_target(${psd} protocols/conn/known-services.bro)
-
-rest_target(${psd} protocols/dns/auth-addl.bro)
-rest_target(${psd} protocols/dns/base.bro)
-rest_target(${psd} protocols/dns/consts.bro)
-rest_target(${psd} protocols/dns/detect.bro)
-
-rest_target(${psd} protocols/ftp/base.bro)
-rest_target(${psd} protocols/ftp/detect.bro)
-rest_target(${psd} protocols/ftp/file-extract.bro)
-rest_target(${psd} protocols/ftp/software.bro)
-rest_target(${psd} protocols/ftp/utils-commands.bro)
-
-rest_target(${psd} protocols/http/base.bro)
-rest_target(${psd} protocols/http/detect-intel.bro)
-rest_target(${psd} protocols/http/detect-sqli.bro)
-rest_target(${psd} protocols/http/detect-webapps.bro)
-rest_target(${psd} protocols/http/file-extract.bro)
-rest_target(${psd} protocols/http/file-hash.bro)
-rest_target(${psd} protocols/http/file-ident.bro)
-rest_target(${psd} protocols/http/headers.bro)
-rest_target(${psd} protocols/http/software.bro)
-rest_target(${psd} protocols/http/utils.bro)
-rest_target(${psd} protocols/http/var-extraction-cookies.bro)
-rest_target(${psd} protocols/http/var-extraction-uri.bro)
-
-rest_target(${psd} protocols/irc/base.bro)
-rest_target(${psd} protocols/irc/dcc-send.bro)
-
-rest_target(${psd} protocols/mime/base.bro)
-rest_target(${psd} protocols/mime/file-extract.bro)
-rest_target(${psd} protocols/mime/file-hash.bro)
-rest_target(${psd} protocols/mime/file-ident.bro)
-
-rest_target(${psd} protocols/smtp/base.bro)
-rest_target(${psd} protocols/smtp/detect.bro)
-rest_target(${psd} protocols/smtp/software.bro)
-
-rest_target(${psd} protocols/ssh/base.bro)
-rest_target(${psd} protocols/ssh/software.bro)
-
-#rest_target(${psd} protocols/ssl/base.bro)
-#rest_target(${psd} protocols/ssl/ssl-ciphers.bro)
-#rest_target(${psd} protocols/ssl/ssl-errors.bro)
-#rest_target(${psd} protocols/ssl/ssl.bro)
-#rest_target(${psd} protocols/ssl/validate.bro)
-
-rest_target(${psd} protocols/syslog/base.bro)
-rest_target(${psd} protocols/syslog/consts.bro)
-
-rest_target(${psd} tuning/defaults/packet-fragments.bro)
-rest_target(${psd} tuning/defaults/remove-high-volume-notices.bro)
-rest_target(${psd} tuning/track-all-assets.bro)
-
-rest_target(${psd} utils/addrs.bro)
-rest_target(${psd} utils/conn_ids.bro)
-rest_target(${psd} utils/directions-and-hosts.bro)
-rest_target(${psd} utils/files.bro)
-rest_target(${psd} utils/numbers.bro)
-rest_target(${psd} utils/paths.bro)
-rest_target(${psd} utils/pattern.bro)
-rest_target(${psd} utils/strings.bro)
-rest_target(${psd} utils/thresholds.bro)
 
 # create temporary list of all docs to include in the master policy/index file
-file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/tmp_policy_index
+set(MASTER_POLICY_INDEX ${CMAKE_CURRENT_BINARY_DIR}/policy_index)
-    "${MASTER_POLICY_INDEX_TEXT}")
+file(WRITE ${MASTER_POLICY_INDEX} "${MASTER_POLICY_INDEX_TEXT}")
+
+# create the temporary list of all packages to include in the master
+# policy/packages.rst file
+set(MASTER_PACKAGE_INDEX ${CMAKE_CURRENT_BINARY_DIR}/pkg_index)
+set(MASTER_PKG_INDEX_TEXT "")
+foreach (pkg ${MASTER_PKG_LIST})
+    # strip of the trailing /index for the link name
+    get_filename_component(lnktxt ${pkg} PATH)
+    set(MASTER_PKG_INDEX_TEXT "${MASTER_PKG_INDEX_TEXT}\n   ${lnktxt} <${pkg}>")
+endforeach ()
+file(WRITE ${MASTER_PACKAGE_INDEX} "${MASTER_PKG_INDEX_TEXT}")
 
 # create temporary file containing list of all groups
 file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/group_list
@@ -280,7 +182,12 @@ if (EXISTS ${RST_OUTPUT_DIR})
         list(FIND ALL_REST_OUTPUTS ${_doc} _found)
         if (_found EQUAL -1)
             file(REMOVE ${_doc})
-            message(STATUS "Removing stale reST doc: ${_doc}")
+            message(STATUS "AutoDoc: remove stale reST doc: ${_doc}")
+            string(REPLACE .rst .bro _brofile ${_doc})
+            if (EXISTS ${_brofile})
+                file(REMOVE ${_brofile})
+                message(STATUS "AutoDoc: remove stale bro source: ${_brofile}")
+            endif ()
         endif ()
     endforeach ()
 endif ()
@@ -315,8 +222,11 @@ add_custom_target(doc
                           ${RST_OUTPUT_DIR}
                           ${DOC_SOURCE_WORKDIR}/policy
                   # append to the master index of all policy scripts
-                  COMMAND cat ${CMAKE_CURRENT_BINARY_DIR}/tmp_policy_index >>
+                  COMMAND cat ${MASTER_POLICY_INDEX} >>
                           ${DOC_SOURCE_WORKDIR}/policy/index.rst
+                  # append to the master index of all policy packages
+                  COMMAND cat ${MASTER_PACKAGE_INDEX} >>
+                          ${DOC_SOURCE_WORKDIR}/packages.rst
                   # construct a reST file for each group
                   COMMAND ${CMAKE_CURRENT_SOURCE_DIR}/group_index_generator.py
                           ${CMAKE_CURRENT_BINARY_DIR}/group_list
@@ -335,7 +245,7 @@ add_custom_target(doc
                           ${CMAKE_BINARY_DIR}/html
                   WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}
                   COMMENT "[Sphinx] Generating HTML policy script docs"
-                  # SOURCES just adds stuff to IDE projects as a convienience
+                  # SOURCES just adds stuff to IDE projects as a convenience
                   SOURCES ${DOC_SOURCES})
 
 # The "docclean" target removes just the Sphinx input/output directories

doc/scripts/DocSourcesList.cmake

@@ -0,0 +1,126 @@
+# This is a list of Bro script sources for which to generate reST documentation.
+# It will be included inline in the CMakeLists.txt found in the same directory
+# in order to create Makefile targets that define how to generate reST from
+# a given Bro script.
+#
+# Note: any path prefix of the script (2nd argument of rest_target macro)
+# will be used to derive what path under policy/ the generated documentation
+# will be placed.
+
+set(psd ${PROJECT_SOURCE_DIR}/policy)
+
+rest_target(${CMAKE_CURRENT_SOURCE_DIR} example.bro internal)
+
+rest_target(${CMAKE_BINARY_DIR}/src bro.bif.bro)
+rest_target(${CMAKE_BINARY_DIR}/src const.bif.bro)
+rest_target(${CMAKE_BINARY_DIR}/src event.bif.bro)
+rest_target(${CMAKE_BINARY_DIR}/src logging.bif.bro)
+rest_target(${CMAKE_BINARY_DIR}/src strings.bif.bro)
+rest_target(${CMAKE_BINARY_DIR}/src types.bif.bro)
+
+rest_target(${psd} bro.init)
+rest_target(${psd} functions.bro)
+rest_target(${psd} site.bro)
+
+rest_target(${psd} detectors/http-MHR.bro)
+
+rest_target(${psd} frameworks/communication/base.bro)
+rest_target(${psd} frameworks/communication/listen-clear.bro)
+rest_target(${psd} frameworks/communication/listen-ssl.bro)
+
+rest_target(${psd} frameworks/dpd/base.bro)
+rest_target(${psd} frameworks/dpd/dyn-disable.bro)
+rest_target(${psd} frameworks/dpd/packet-segment-logging.bro)
+
+rest_target(${psd} frameworks/intel/base.bro)
+
+rest_target(${psd} frameworks/logging/base.bro)
+rest_target(${psd} frameworks/logging/plugins/ascii.bro)
+
+rest_target(${psd} frameworks/metrics/base.bro)
+rest_target(${psd} frameworks/metrics/conn-example.bro)
+rest_target(${psd} frameworks/metrics/http-example.bro)
+
+rest_target(${psd} frameworks/notice/action-filters.bro)
+rest_target(${psd} frameworks/notice/base.bro)
+rest_target(${psd} frameworks/notice/weird.bro)
+
+rest_target(${psd} frameworks/packet-filter/base.bro)
+rest_target(${psd} frameworks/packet-filter/netstats.bro)
+
+rest_target(${psd} frameworks/signatures/base.bro)
+
+rest_target(${psd} frameworks/software/base.bro)
+rest_target(${psd} frameworks/software/vulnerable.bro)
+
+rest_target(${psd} integration/barnyard2/base.bro)
+rest_target(${psd} integration/barnyard2/event.bro)
+rest_target(${psd} integration/barnyard2/types.bro)
+
+rest_target(${psd} protocols/conn/base.bro)
+rest_target(${psd} protocols/conn/contents.bro)
+rest_target(${psd} protocols/conn/inactivity.bro)
+rest_target(${psd} protocols/conn/known-hosts.bro)
+rest_target(${psd} protocols/conn/known-services.bro)
+
+rest_target(${psd} protocols/dns/auth-addl.bro)
+rest_target(${psd} protocols/dns/base.bro)
+rest_target(${psd} protocols/dns/consts.bro)
+rest_target(${psd} protocols/dns/detect.bro)
+
+rest_target(${psd} protocols/ftp/base.bro)
+rest_target(${psd} protocols/ftp/detect.bro)
+rest_target(${psd} protocols/ftp/file-extract.bro)
+rest_target(${psd} protocols/ftp/software.bro)
+rest_target(${psd} protocols/ftp/utils-commands.bro)
+
+rest_target(${psd} protocols/http/base.bro)
+rest_target(${psd} protocols/http/detect-intel.bro)
+rest_target(${psd} protocols/http/detect-sqli.bro)
+rest_target(${psd} protocols/http/detect-webapps.bro)
+rest_target(${psd} protocols/http/file-extract.bro)
+rest_target(${psd} protocols/http/file-hash.bro)
+rest_target(${psd} protocols/http/file-ident.bro)
+rest_target(${psd} protocols/http/headers.bro)
+rest_target(${psd} protocols/http/software.bro)
+rest_target(${psd} protocols/http/utils.bro)
+rest_target(${psd} protocols/http/var-extraction-cookies.bro)
+rest_target(${psd} protocols/http/var-extraction-uri.bro)
+
+rest_target(${psd} protocols/irc/base.bro)
+rest_target(${psd} protocols/irc/dcc-send.bro)
+
+rest_target(${psd} protocols/mime/base.bro)
+rest_target(${psd} protocols/mime/file-extract.bro)
+rest_target(${psd} protocols/mime/file-hash.bro)
+rest_target(${psd} protocols/mime/file-ident.bro)
+
+rest_target(${psd} protocols/smtp/base.bro)
+rest_target(${psd} protocols/smtp/detect.bro)
+rest_target(${psd} protocols/smtp/software.bro)
+
+rest_target(${psd} protocols/ssh/base.bro)
+rest_target(${psd} protocols/ssh/software.bro)
+
+#rest_target(${psd} protocols/ssl/base.bro)
+#rest_target(${psd} protocols/ssl/ssl-ciphers.bro)
+#rest_target(${psd} protocols/ssl/ssl-errors.bro)
+#rest_target(${psd} protocols/ssl/ssl.bro)
+#rest_target(${psd} protocols/ssl/validate.bro)
+
+rest_target(${psd} protocols/syslog/base.bro)
+rest_target(${psd} protocols/syslog/consts.bro)
+
+rest_target(${psd} tuning/defaults/packet-fragments.bro)
+rest_target(${psd} tuning/defaults/remove-high-volume-notices.bro)
+rest_target(${psd} tuning/track-all-assets.bro)
+
+rest_target(${psd} utils/addrs.bro)
+rest_target(${psd} utils/conn_ids.bro)
+rest_target(${psd} utils/directions-and-hosts.bro)
+rest_target(${psd} utils/files.bro)
+rest_target(${psd} utils/numbers.bro)
+rest_target(${psd} utils/paths.bro)
+rest_target(${psd} utils/pattern.bro)
+rest_target(${psd} utils/strings.bro)
+rest_target(${psd} utils/thresholds.bro)

doc/scripts/README

@@ -38,15 +38,19 @@ by CMake:
 
     This target removes Sphinx inputs and outputs from the CMake ``build/`` dir.
 
-To schedule a script to be documented, edit ``CMakeLists.txt`` inside this
+To schedule a script to be documented, edit ``DocSourcesList.cmake`` inside
-directory add a call to the ``rest_target()`` macro.  Calling that macro
+this directory add a call to the ``rest_target()`` macro.  Calling that macro
-with a group name for the script is optional, but if not given, the only
+with a group name for the script is optional.  If the group is omitted, the
-link to the script will be in the master TOC tree for all policy scripts.
+only links to the script will be in the master TOC tree for all policy scripts
+as well as the master TOC tree for script packages (derived from the path
+component of the second argument to ``rest_target()``), with the exception
+of ``.bif`` files which are grouped automatically.
 
-When adding a new logical grouping for generated scripts, create a new
+When adding a new logical grouping e.g. "my/group" (groups are allowed
-reST document in ``source/<group_name>.rst`` and add some default
+to contain slashes specifying a path) for generated scripts,
+create a new reST document in ``source/my/group.rst`` and add some default
 documentation for the group.  References to (and summaries of) documents
-associated with the group get appended to this file during the
+associated with the group get appended to this pre-created file during the
 ``make doc`` process.
 
 The Sphinx source tree template in ``source/`` can be modified to add more

doc/scripts/conf.py.in

@@ -40,7 +40,7 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'Bro'
-copyright = u'2011, Jon Siwek'
+copyright = u'2011, The Bro Project'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -178,7 +178,7 @@ htmlhelp_basename = 'Brodoc'
 # (source start file, target name, title, author, documentclass [howto/manual]).
 latex_documents = [
   ('index', 'Bro.tex', u'Bro Documentation',
-   u'Jon Siwek', 'manual'),
+   u'The Bro Project', 'manual'),
 ]
 
 # The name of an image file (relative to this directory) to place at the top of
@@ -211,5 +211,5 @@ latex_documents = [
 # (source start file, name, description, authors, manual section).
 man_pages = [
     ('index', 'bro', u'Bro Documentation',
-     [u'Jon Siwek'], 1)
+     [u'The Bro Project'], 1)
 ]

doc/scripts/group_index_generator.py

@@ -46,6 +46,16 @@ with open(group_list, 'r') as f_group_list:
                         summary_comments.append(line[(sum_pos+3):])
             #print summary_comments
             group_file = os.path.join(output_dir, group + ".rst")
+            if not os.path.exists(group_file):
+                if not os.path.exists(os.path.dirname(group_file)):
+                    os.makedirs(os.path.dirname(group_file))
+                with open(group_file, 'w') as f_group_file:
+                    title = "Package Index: %s\n" % os.path.dirname(group)
+                    f_group_file.write(title);
+                    for n in range(len(title)):
+                        f_group_file.write("=")
+                    f_group_file.write("\n");
+
             with open(group_file, 'a') as f_group_file:
                 f_group_file.write("\n:doc:`/policy/%s`\n" % doc_names[i])
                 for line in summary_comments:

doc/scripts/source/builtins.rst

@@ -64,11 +64,6 @@ The Bro scripting language supports the following built-in types.
 
 .. 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
 ----------
 

doc/scripts/source/default.rst

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

doc/scripts/source/index.rst

@@ -11,20 +11,10 @@ Contents:
 
    common
    builtins
-   default
-   bifs
-   policy/dns-index
-   policy/ftp-index
-   policy/http-index
-   policy/irc-index
-   policy/metrics-index
-   policy/mime-index
-   policy/sig-index
-   policy/smtp-index
-   policy/software-index
-   policy/ssh-index
-   policy/ssl-index
    internal
+   bifs
+   packages
+   collections
    policy/index
 
 Indices and tables

doc/scripts/source/packages.rst

@@ -0,0 +1,13 @@
+.. This is a stub doc to which the build process can append.
+
+Policy Script Packages
+======================
+
+Bro has the following policy script packages (e.g. collections of related
+policy scripts).  If the package contains a ``__load__.bro`` script, it
+supports being loaded in mass as a whole directory for convenience.
+
+.. toctree::
+   :maxdepth: 1
+
+

doc/scripts/source/policy/dns-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-DNS Policy Scripts
-==================
-

doc/scripts/source/policy/ftp-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-FTP Policy Scripts
-==================
-

doc/scripts/source/policy/http-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-HTTP Policy Scripts
-===================
-

doc/scripts/source/policy/irc-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-IRC Policy Scripts
-==================
-

doc/scripts/source/policy/metrics-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-Metrics Policy Scripts
-======================
-

doc/scripts/source/policy/mime-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-MIME Policy Scripts
-===================
-

doc/scripts/source/policy/sig-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-Signature Policy Scripts
-========================
-

doc/scripts/source/policy/smtp-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-SMTP Policy Scripts
-===================
-

doc/scripts/source/policy/software-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-Software Policy Scripts
-=======================
-

doc/scripts/source/policy/ssh-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-SSH Policy Scripts
-==================
-

doc/scripts/source/policy/ssl-index.rst

@@ -1,5 +0,0 @@
-.. This is a stub doc to which the build process can append.
-
-SSL Policy Scripts
-==================
-

src/BroDoc.cc

@@ -93,7 +93,6 @@ void BroDoc::AddImport(const std::string& s)
 		if ( streq(filename, PACKAGE_LOADER) )
 			{
 			// link to the package's index
-			// TODO: check that this works
 			string pkg(subpath);
 			pkg += "/index";
 			imports.push_back(pkg);
@@ -180,7 +179,11 @@ void BroDoc::WriteDocFile() const
 			if ( it != imports.begin() )
 				WriteToDoc(", ");
 
-			WriteToDoc(":doc:`%s </policy/%s>`", it->c_str(), it->c_str());
+			string pretty(*it);
+			size_t pos = pretty.find("/index");
+			if ( pos != std::string::npos && pos + 6 == pretty.size() )
+				pretty = pretty.substr(0, pos);
+			WriteToDoc(":doc:`%s </policy/%s>`", pretty.c_str(), it->c_str());
 			}
 		WriteToDoc("\n");
 		}

testing/btest/Baseline/doc.autogen-reST-example/example.rst

@@ -29,7 +29,7 @@ each of "columns", "event", "filter" depending on exactly what it's doing.
 
 :Author: Jon Siwek <jsiwek@ncsa.illinois.edu>
 
-:Imports: :doc:`frameworks/notice/index </policy/frameworks/notice/index>`
+:Imports: :doc:`frameworks/notice </policy/frameworks/notice/index>`
 
 Summary
 ~~~~~~~