mirror of
https://github.com/zeek/zeek.git
synced 2025-10-02 14:48:21 +00:00
4ac6d0ae2e
- 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
71 lines
3.1 KiB
Text
71 lines
3.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:
|
|
|
|
``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.
|