mirror of
https://github.com/zeek/zeek.git
synced 2025-10-04 15:48:19 +00:00
5a2cd265ab
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.
65 lines
2.8 KiB
Text
65 lines
2.8 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.
|
|
|
|
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 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 pre-created file during the
|
|
``make doc`` process.
|
|
|
|
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.
|