Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-17 05:58:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Overhaul of "doc" build target for generating policy script documentation.

Browse source 
It's now all implemented in CMake scripting.

The generation of reST docs is now a distinct target, "restdoc", while
the target to generate HTML docs, "doc", depends on "restdoc".  reST doc
generation supports incremental builds (documentation for a given policy
script is only regenerated when it is out of date), but HTML doc generation
via ``make doc`` is not incremental (Sphinx always starts with fresh input).

Building the "restdoc" target is now covered by a btest to ensure all
policy scripts are parse-able when Bro is in "doc mode".

Generated reST docs should now support "@load"ing from subdirectories.  e.g.
"@load foo/baz" and "@load bar/baz" will now generate the right xref links.
This commit is contained in:
Jon Siwek 2011-04-26 22:13:04 -05:00
parent 9875c2ba9c
commit f10d2e10ea
14 changed files with 276 additions and 278 deletions
Download patch file Download diff file Expand all files Collapse all files

49
doc/scripts/README
View file

@ -1,8 +1,21 @@
This directory contains scripts and templates that can be used to automate
the generation of Bro script documentation. Two build targets are defined
the generation of Bro script documentation. Several build targets are defined
by CMake:
``make doc``
``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
@ -10,27 +23,31 @@ by CMake:
> sudo easy_install sphinx
This target will also first build the bro binary if it is not already
since the generation of reStructuredText (reST) documentation from
Bro scripts is integrated within the parsing process.
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 inside the CMake
``build/`` directory as ``doc/scripts/out/html``. The generated
reST documentation will be located in ``doc/scripts/source/policy``.
After completion, HTML documentation can be located in the CMake
``build/`` directory inside ``html`` (a symlink to
``doc/scripts/out/html``)
``make doc-clean``
``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 ``scripts/generate_reST_docs.py.in``
and try adding the name of the script along with an optional script group to
the ``docs`` dictionary. That python script also shows other, more specialized
methods for generating documentation for some types of corner-cases.
To schedule a script to be documented, edit ``CMakeLists.txt`` inside this
directory add a call to the ``rest_target()`` macro. Calling that macro
with a group name for the script is optional, but if not given, the only
link to the script will be in the master TOC tree for all policy scripts.
When adding a new logical grouping for generated scripts, create a new
reST document in ``source/policy/<group_name>.rst`` and add some default
documentation. References to (and summaries of) documents associated with
the group get appended to this file during the ``make doc`` process.
reST document in ``source/<group_name>.rst`` and add some default
documentation for the group. References to (and summaries of) documents
associated with the group get appended to this 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