I made a light pass over the text. Switched the includes over to the
new btest-include and adapted the other TEXT-EXECs a bit.
Also includes more tweaking all over the Sphinx setup.
I edited the text little bit, reorganized the structure somewhat and
extended some parts. I've also simplified the tests a bit, using some
of the BTest tweaks commited in parallel.
Include explanation of various Notice::policy hook actions.
Add two btest scripts. framework_notice_hook_01.bro shows adding an
action to the n$action set while framework_notice_suppression.bro shows
how to add a custom n$suppress_for value for a notice through a policy
hook. While both scripts include an @load directive, it is left out in
RST document so as to avoid confusion.
The names of enum types are tracked so that variables holding a value
of a given enum type can generate a reference to it instead of just
listing the type as a generic "enum".
Updated README and collected coverage-related tests in a common dir.
There are still coverage failures resulting from either the following
scripts not being @load'd in the default bro mode:
base/frameworks/time-machine/notice.bro
base/protocols/http/partial-content.bro
base/protocols/rpc/main.bro
Or the following result in errors when @load'd:
policy/protocols/conn/scan.bro
policy/hot.conn.bro
If these are all scripts-in-progress, can we move them all to live
outside the main scripts/ directory until they're ready?
- Reorganize top-level 'doc' Makefile target so submodules can easily
add their own doc-generating routines to it. e.g. the Bro project
makes a placeholder 'doc' target, then adds 'restdoc', 'sphinxdoc';
later Broccoli can add it's own target as a dependency for generating
API docs.
- Fixed generated docs for BIFs not being organized under a base/
subdirectory like the original source files.
- Fixed documentation style for function parameters not applying to
functions declared as record fields.
- Misc. script documentation tweaks to address warnings given by Sphinx.
- 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
- The CMake targets for generating reST docs from policy scripts are now
automatically generated via the genDocSourcesList.sh script
- Fixed a lot of parsing errors in policy scripts that I saw along the way
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.
Adds a diff canonifier that skips diffing the places where example.bro
may use MutableVal derivatives (e.g. sets/tables), which don't always
generate the same ordering in the reST docs across runs.
