zeek/doc/scripts

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:

``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``).

``doc``

    This target depends on a Python interpreter (>=2.5) and
    `Sphinx <http://sphinx.pocoo.org/>`_ being installed.  Sphinx can be
    installed like::

        > sudo easy_install sphinx

    This target will first build ``restdoc`` target and then copy the
    resulting reST files as an input directory to Sphinx.

    After completion, HTML documentation can be located in the CMake
    ``build/`` directory inside ``html`` (a symlink to
    ``doc/scripts/out/html``)

``restclean``

    This target removes any reST documentation that has been generated so far.

``docclean``

    This target removes Sphinx inputs and outputs from the CMake ``build/`` dir.

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 ``source/index.rst``.

The Sphinx source tree template in ``source/`` can be modified to add more
common/general documentation, style sheets, JavaScript, etc.  The Sphinx
config file is produced from ``conf.py.in``, so that can be edited to change
various Sphinx options, like setting the default HTML rendering theme.
There is also a custom Sphinx domain implemented in ``source/ext/bro.py``
which adds some reST directives and roles that aid in generating useful
index entries and cross-references.

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.