From 5a2cd265abcd7efabfabdd6478ea31bdd64da772 Mon Sep 17 00:00:00 2001 From: Jon Siwek Date: Thu, 30 Jun 2011 16:58:20 -0500 Subject: [PATCH 1/2] 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 | 204 +++++------------- doc/scripts/DocSourcesList.cmake | 126 +++++++++++ doc/scripts/README | 18 +- doc/scripts/conf.py.in | 6 +- doc/scripts/group_index_generator.py | 10 + doc/scripts/source/builtins.rst | 5 - doc/scripts/source/default.rst | 3 - doc/scripts/source/index.rst | 16 +- doc/scripts/source/packages.rst | 13 ++ doc/scripts/source/policy/dns-index.rst | 5 - doc/scripts/source/policy/ftp-index.rst | 5 - doc/scripts/source/policy/http-index.rst | 5 - doc/scripts/source/policy/irc-index.rst | 5 - doc/scripts/source/policy/metrics-index.rst | 5 - doc/scripts/source/policy/mime-index.rst | 5 - doc/scripts/source/policy/sig-index.rst | 5 - doc/scripts/source/policy/smtp-index.rst | 5 - doc/scripts/source/policy/software-index.rst | 5 - doc/scripts/source/policy/ssh-index.rst | 5 - doc/scripts/source/policy/ssl-index.rst | 5 - src/BroDoc.cc | 7 +- .../doc.autogen-reST-example/example.rst | 2 +- 22 files changed, 229 insertions(+), 236 deletions(-) create mode 100644 doc/scripts/DocSourcesList.cmake delete mode 100644 doc/scripts/source/default.rst create mode 100644 doc/scripts/source/packages.rst delete mode 100644 doc/scripts/source/policy/dns-index.rst delete mode 100644 doc/scripts/source/policy/ftp-index.rst delete mode 100644 doc/scripts/source/policy/http-index.rst delete mode 100644 doc/scripts/source/policy/irc-index.rst delete mode 100644 doc/scripts/source/policy/metrics-index.rst delete mode 100644 doc/scripts/source/policy/mime-index.rst delete mode 100644 doc/scripts/source/policy/sig-index.rst delete mode 100644 doc/scripts/source/policy/smtp-index.rst delete mode 100644 doc/scripts/source/policy/software-index.rst delete mode 100644 doc/scripts/source/policy/ssh-index.rst delete mode 100644 doc/scripts/source/policy/ssl-index.rst diff --git a/doc/scripts/CMakeLists.txt b/doc/scripts/CMakeLists.txt index d01360f503..d05d677e3a 100644 --- a/doc/scripts/CMakeLists.txt +++ b/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 -# group: optional name of group that the script documentation will belong to +# broInput: the file name of a bro policy script, any path prefix of this +# 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 "${MASTER_POLICY_INDEX_TEXT}\n${indexEntry}") + set(MASTER_POLICY_INDEX_TEXT + "${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. -# -# 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) +include(DocSourcesList.cmake) # create temporary list of all docs to include in the master policy/index file -file(WRITE ${CMAKE_CURRENT_BINARY_DIR}/tmp_policy_index - "${MASTER_POLICY_INDEX_TEXT}") +set(MASTER_POLICY_INDEX ${CMAKE_CURRENT_BINARY_DIR}/policy_index) +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 diff --git a/doc/scripts/DocSourcesList.cmake b/doc/scripts/DocSourcesList.cmake new file mode 100644 index 0000000000..6c33153426 --- /dev/null +++ b/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) diff --git a/doc/scripts/README b/doc/scripts/README index 85496322d9..93700ab012 100644 --- a/doc/scripts/README +++ b/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 -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 -link to the script will be in the master TOC tree for all policy scripts. +To schedule a script to be documented, edit ``DocSourcesList.cmake`` inside +this directory add a call to the ``rest_target()`` macro. Calling that macro +with a group name for the script is optional. If the group is omitted, the +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 -reST document in ``source/.rst`` and add some default +When adding a new logical grouping e.g. "my/group" (groups are allowed +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 diff --git a/doc/scripts/conf.py.in b/doc/scripts/conf.py.in index 67e06abfb3..419209f580 100644 --- a/doc/scripts/conf.py.in +++ b/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) ] diff --git a/doc/scripts/group_index_generator.py b/doc/scripts/group_index_generator.py index d143765ef9..74c8c14d65 100755 --- a/doc/scripts/group_index_generator.py +++ b/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: diff --git a/doc/scripts/source/builtins.rst b/doc/scripts/source/builtins.rst index d1c551339d..e6a9e9b829 100644 --- a/doc/scripts/source/builtins.rst +++ b/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 ---------- diff --git a/doc/scripts/source/default.rst b/doc/scripts/source/default.rst deleted file mode 100644 index 6b79f20c79..0000000000 --- a/doc/scripts/source/default.rst +++ /dev/null @@ -1,3 +0,0 @@ -Bro Scripts Loaded by Default -============================= - diff --git a/doc/scripts/source/index.rst b/doc/scripts/source/index.rst index 049b548896..29e2fa396a 100644 --- a/doc/scripts/source/index.rst +++ b/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 diff --git a/doc/scripts/source/packages.rst b/doc/scripts/source/packages.rst new file mode 100644 index 0000000000..a7e76f097a --- /dev/null +++ b/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 + + diff --git a/doc/scripts/source/policy/dns-index.rst b/doc/scripts/source/policy/dns-index.rst deleted file mode 100644 index 69a3ef0c52..0000000000 --- a/doc/scripts/source/policy/dns-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -DNS Policy Scripts -================== - diff --git a/doc/scripts/source/policy/ftp-index.rst b/doc/scripts/source/policy/ftp-index.rst deleted file mode 100644 index 01aafb28f0..0000000000 --- a/doc/scripts/source/policy/ftp-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -FTP Policy Scripts -================== - diff --git a/doc/scripts/source/policy/http-index.rst b/doc/scripts/source/policy/http-index.rst deleted file mode 100644 index 67216d6f1f..0000000000 --- a/doc/scripts/source/policy/http-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -HTTP Policy Scripts -=================== - diff --git a/doc/scripts/source/policy/irc-index.rst b/doc/scripts/source/policy/irc-index.rst deleted file mode 100644 index 5b34d3795f..0000000000 --- a/doc/scripts/source/policy/irc-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -IRC Policy Scripts -================== - diff --git a/doc/scripts/source/policy/metrics-index.rst b/doc/scripts/source/policy/metrics-index.rst deleted file mode 100644 index 3cef07d231..0000000000 --- a/doc/scripts/source/policy/metrics-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -Metrics Policy Scripts -====================== - diff --git a/doc/scripts/source/policy/mime-index.rst b/doc/scripts/source/policy/mime-index.rst deleted file mode 100644 index 87d73dd392..0000000000 --- a/doc/scripts/source/policy/mime-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -MIME Policy Scripts -=================== - diff --git a/doc/scripts/source/policy/sig-index.rst b/doc/scripts/source/policy/sig-index.rst deleted file mode 100644 index 2ba63ea28c..0000000000 --- a/doc/scripts/source/policy/sig-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -Signature Policy Scripts -======================== - diff --git a/doc/scripts/source/policy/smtp-index.rst b/doc/scripts/source/policy/smtp-index.rst deleted file mode 100644 index ba0b29996c..0000000000 --- a/doc/scripts/source/policy/smtp-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -SMTP Policy Scripts -=================== - diff --git a/doc/scripts/source/policy/software-index.rst b/doc/scripts/source/policy/software-index.rst deleted file mode 100644 index 01683de20b..0000000000 --- a/doc/scripts/source/policy/software-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -Software Policy Scripts -======================= - diff --git a/doc/scripts/source/policy/ssh-index.rst b/doc/scripts/source/policy/ssh-index.rst deleted file mode 100644 index 31c3455f3d..0000000000 --- a/doc/scripts/source/policy/ssh-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -SSH Policy Scripts -================== - diff --git a/doc/scripts/source/policy/ssl-index.rst b/doc/scripts/source/policy/ssl-index.rst deleted file mode 100644 index 348b91584c..0000000000 --- a/doc/scripts/source/policy/ssl-index.rst +++ /dev/null @@ -1,5 +0,0 @@ -.. This is a stub doc to which the build process can append. - -SSL Policy Scripts -================== - diff --git a/src/BroDoc.cc b/src/BroDoc.cc index e71026a250..2f14ff6c4d 100644 --- a/src/BroDoc.cc +++ b/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 `", 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 `", pretty.c_str(), it->c_str()); } WriteToDoc("\n"); } diff --git a/testing/btest/Baseline/doc.autogen-reST-example/example.rst b/testing/btest/Baseline/doc.autogen-reST-example/example.rst index d9a6fd0adf..2c2ed28369 100644 --- a/testing/btest/Baseline/doc.autogen-reST-example/example.rst +++ b/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 -:Imports: :doc:`frameworks/notice/index ` +:Imports: :doc:`frameworks/notice ` Summary ~~~~~~~ From 9242f179783fcb3a4b3ea2364b65ad138fed09fe Mon Sep 17 00:00:00 2001 From: Jon Siwek Date: Thu, 30 Jun 2011 17:12:35 -0500 Subject: [PATCH 2/2] Add RPC/SSL scripts to doc generation target. --- doc/scripts/DocSourcesList.cmake | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/doc/scripts/DocSourcesList.cmake b/doc/scripts/DocSourcesList.cmake index 6c33153426..570bb35e5b 100644 --- a/doc/scripts/DocSourcesList.cmake +++ b/doc/scripts/DocSourcesList.cmake @@ -95,6 +95,8 @@ 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/rpc/base.bro) + rest_target(${psd} protocols/smtp/base.bro) rest_target(${psd} protocols/smtp/detect.bro) rest_target(${psd} protocols/smtp/software.bro) @@ -102,11 +104,10 @@ 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/ssl/base.bro) +rest_target(${psd} protocols/ssl/consts.bro) +rest_target(${psd} protocols/ssl/known-certs.bro) +rest_target(${psd} protocols/ssl/mozilla-ca-list.bro) rest_target(${psd} protocols/syslog/base.bro) rest_target(${psd} protocols/syslog/consts.bro)