Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-08 01:28:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 3

Fixes for script auto-documentation.

Browse source 
- Fixing the parts of the `make restdoc` and `make doc` process that were
  broken by the last Bro script re-organization

- Generated documentation for Bro scripts derived from BiFs now use the
  original BiF source file as the "original source file" link

- Renaming of the internal POLICYDEST definition and other misc places that
  refer to "policy" scripts; that terminology doesn't make total sense now

- Added a documentation blacklist reminder test that will fail if there's
  scripts that are blacklisted from being documentated because they're still
  in progress

- Some minor Bro script changes to fix small @load dependency errors

Addresses #543
This commit is contained in:
Jon Siwek 2011-08-08 19:50:45 -05:00
parent 0e2a1605b3
commit 4ac6d0ae2e
40 changed files with 178 additions and 154 deletions
Download patch file Download diff file Expand all files Collapse all files

10
doc/scripts/CMakeLists.txt
View file

@ -57,10 +57,12 @@ macro(REST_TARGET srcDir broInput)
get_filename_component(relDstDir ${broInput} PATH)
set(sumTextSrc ${absSrcPath})
set(ogSourceFile ${absSrcPath})
if (${extension} STREQUAL ".bif.bro")
set(ogSourceFile ${BIF_SRC_DIR}/${basename})
# 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})
set(sumTextSrc ${ogSourceFile})
endif ()
if (NOT relDstDir)
@ -124,9 +126,9 @@ macro(REST_TARGET srcDir broInput)
ARGS -E make_directory ${dstDir}
COMMAND "${CMAKE_COMMAND}"
ARGS -E copy ${restFile} ${restOutput}
# copy the bro policy script, too
# copy the bro or bif script, too
COMMAND "${CMAKE_COMMAND}"
ARGS -E copy ${absSrcPath} ${dstDir}
ARGS -E copy ${ogSourceFile} ${dstDir}
# clean up the build directory
COMMAND rm
ARGS -rf .state *.log *.rst
@ -151,6 +153,8 @@ 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)
# pretty-up the link name by removing common scripts/ prefix
string(REPLACE "scripts/" "" lnktxt "${lnktxt}")
set(MASTER_PKG_INDEX_TEXT "${MASTER_PKG_INDEX_TEXT}\n ${lnktxt} <${pkg}>")
endforeach ()
file(WRITE ${MASTER_PACKAGE_INDEX} "${MASTER_PKG_INDEX_TEXT}")

19
doc/scripts/DocSourcesList.cmake
View file

@ -13,22 +13,14 @@
set(psd ${PROJECT_SOURCE_DIR}/scripts)
rest_target(${CMAKE_CURRENT_SOURCE_DIR} example.bro internal)
rest_target(${psd} base/bro.init internal)
rest_target(${psd} base/all.bro internal)
rest_target(${psd} base/init-default.bro internal)
rest_target(${psd} base/init-bare.bro internal)
rest_target(${CMAKE_BINARY_DIR}/src bro.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src common-rw.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src const.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src dns-rw.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src event.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src finger-rw.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src ftp-rw.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src http-rw.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src ident-rw.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src logging.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src reporter.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src smb-rw.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src smtp-rw.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src strings.bif.bro)
rest_target(${CMAKE_BINARY_DIR}/src types.bif.bro)
rest_target(${psd} base/frameworks/cluster/main.bro)
@ -56,6 +48,7 @@ rest_target(${psd} base/frameworks/packet-filter/netstats.bro)
rest_target(${psd} base/frameworks/reporter/main.bro)
rest_target(${psd} base/frameworks/signatures/main.bro)
rest_target(${psd} base/frameworks/software/main.bro)
rest_target(${psd} base/frameworks/time-machine/notice.bro)
rest_target(${psd} base/protocols/conn/contents.bro)
rest_target(${psd} base/protocols/conn/inactivity.bro)
rest_target(${psd} base/protocols/conn/main.bro)
@ -72,6 +65,11 @@ rest_target(${psd} base/protocols/http/partial-content.bro)
rest_target(${psd} base/protocols/http/utils.bro)
rest_target(${psd} base/protocols/irc/dcc-send.bro)
rest_target(${psd} base/protocols/irc/main.bro)
rest_target(${psd} base/protocols/mime/base.bro)
rest_target(${psd} base/protocols/mime/file-extract.bro)
rest_target(${psd} base/protocols/mime/file-hash.bro)
rest_target(${psd} base/protocols/mime/file-ident.bro)
rest_target(${psd} base/protocols/rpc/base.bro)
rest_target(${psd} base/protocols/smtp/main.bro)
rest_target(${psd} base/protocols/ssh/main.bro)
rest_target(${psd} base/protocols/ssl/consts.bro)
@ -105,7 +103,6 @@ rest_target(${psd} policy/misc/loaded-scripts.bro)
rest_target(${psd} policy/misc/trim-trace-file.bro)
rest_target(${psd} policy/protocols/conn/known-hosts.bro)
rest_target(${psd} policy/protocols/conn/known-services.bro)
rest_target(${psd} policy/protocols/conn/scan.bro)
rest_target(${psd} policy/protocols/dns/auth-addl.bro)
rest_target(${psd} policy/protocols/dns/detect-external-names.bro)
rest_target(${psd} policy/protocols/ftp/detect.bro)

2
doc/scripts/README
View file

@ -44,7 +44,7 @@ of documentation targets. This script should be run after adding new
Bro script source files, and the changes commited to git.
If a script shouldn't have documentation generated for it, there's also a
blacklist variable that can be maintained in the ``genDocSourcesList.sh``
blacklist manifest that can be maintained in the ``genDocSourcesList.sh``
script.
The blacklist can also be used if you want to define a certain grouping for

33
doc/scripts/genDocSourcesList.sh
View file

@ -11,8 +11,31 @@
# Specific scripts can be blacklisted below when e.g. they currently aren't
# parseable or they just aren't meant to be documented.
blacklist="__load__.bro|test-all.bro|all.bro"
blacklist_addl="hot.conn.bro"
blacklist ()
{
if [[ "$blacklist" == "" ]]; then
blacklist="$1"
else
blacklist="$blacklist|$1"
fi
}
# files passed into this function are meant to be temporary workarounds
# because they're not finished or otherwise can't be loaded for some reason
tmp_blacklist ()
{
echo "Warning: temporarily blacklisted files named '$1'" 1>&2
blacklist $1
}
blacklist __load__.bro
blacklist test-all.bro
blacklist all.bro
blacklist init-default.bro
blacklist init-bare.bro
tmp_blacklist hot.conn.bro
tmp_blacklist scan.bro
statictext="\
# DO NOT EDIT
@ -30,8 +53,8 @@ statictext="\
set(psd \${PROJECT_SOURCE_DIR}/scripts)
rest_target(\${CMAKE_CURRENT_SOURCE_DIR} example.bro internal)
rest_target(\${psd} base/bro.init internal)
rest_target(\${psd} base/all.bro internal)
rest_target(\${psd} base/init-default.bro internal)
rest_target(\${psd} base/init-bare.bro internal)
"
if [[ $# -ge 1 ]]; then
@ -58,7 +81,7 @@ scriptfiles=`( cd ${sourcedir}/scripts && find . -name \*\.bro | sort )`
for file in $scriptfiles
do
f=${file:2}
if [[ (! $f =~ $blacklist) && (! $f =~ $blacklist_addl) ]]; then
if [[ ! $f =~ $blacklist ]]; then
echo "rest_target(\${psd} $f)" >> $outfile
fi
done

7
doc/scripts/group_index_generator.py
View file

@ -1,9 +1,8 @@
#! /usr/bin/env python
# This script automatically generates a reST documents that lists
# a collection of Bro policy scripts that are "grouped" together.
# The summary text (##! comments) of the policy script is embedded
# in the list.
# a collection of Bro scripts that are "grouped" together.
# The summary text (##! comments) of the script is embedded in the list
#
# 1st argument is the file containing list of groups
# 2nd argument is the directory containing ${group}_files lists of
@ -57,6 +56,6 @@ with open(group_list, 'r') as f_group_list:
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])
f_group_file.write("\n:doc:`/scripts/%s`\n" % doc_names[i])
for line in summary_comments:
f_group_file.write(" " + line)

2
doc/scripts/source/index.rst
View file

@ -14,7 +14,7 @@ Contents:
internal
bifs
packages
policy/index
scripts/index
Indices and tables
==================

4
doc/scripts/source/internal.rst
View file

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

14
doc/scripts/source/packages.rst
View file

@ -1,11 +1,15 @@
.. This is a stub doc to which the build process can append.
Policy Script Packages
======================
Bro 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.
Bro has the following script packages (e.g. collections of related scripts in
a common directory). If the package directory contains a ``__load__.bro``
script, it supports being loaded in mass as a whole directory for convenience.
Packages/scripts in the ``base/`` directory are all loaded by default, while
ones in ``policy/`` provide functionality and customization options that are
more appropriate for users to decide whether they'd like to load it or not.
.. toctree::
:maxdepth: 1

6
doc/scripts/source/policy/index.rst
View file

@ -1,6 +0,0 @@
Index of All Policy Script Documentation
========================================
.. toctree::
:maxdepth: 1

6
doc/scripts/source/scripts/index.rst Normal file
View file

@ -0,0 +1,6 @@
Index of All Bro Script Documentation
=====================================
.. toctree::
:maxdepth: 1