mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 14:48:21 +00:00
44 lines
2.1 KiB
Text
44 lines
2.1 KiB
Text
This directory contains scripts and templates that can be used to automate
|
|
the generation of Bro script documentation. Several build targets are defined
|
|
by CMake and available in the top-level Makefile:
|
|
|
|
``restdoc``
|
|
|
|
This target uses Bro to parse policy scripts in order to generate
|
|
reStructuredText (reST) documentation from them. The list of scripts
|
|
for which to generate reST documentation is defined in the
|
|
``CMakeLists.txt`` file in this directory. Script documentation is
|
|
rebuild automatically if the policy script from which it is derived
|
|
or the Bro binary becomes out of date
|
|
|
|
The resulting output from this target can be found in the CMake
|
|
``build/`` directory inside ``reST`` (a symlink to
|
|
``doc/scripts/rest_output``).
|
|
|
|
``restclean``
|
|
|
|
This target removes any reST documentation that has been generated so far.
|
|
|
|
The ``genDocSourcesList.sh`` script can be run to automatically generate
|
|
``DocSourcesList.cmake``, which is the file CMake uses to define the list
|
|
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 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
|
|
the script's generated docs to belong to (as opposed to the automatic grouping
|
|
the happens for script packages/directories). To do that, add the
|
|
script's name to the blacklist, then append a ``rest_target()`` to the
|
|
``statictext`` variable where the first argument is the source directory
|
|
containing the policy script to document, the second argument is the file
|
|
name of the policy script, and the third argument is the path/name of a
|
|
pre-created reST document in the ``../`` source directory to which the
|
|
``make doc`` process can append script documentation references. This
|
|
pre-created reST document should also then be linked to from the TOC tree
|
|
in ``../index.rst``.
|
|
|
|
See ``example.bro`` for an example of how to document a Bro script such that
|
|
``make doc`` will be able to produce reST/HTML documentation for it.
|