Some of the examples in the scripting tutorial were regularly getting
out of sync with the base scripts (because the line numbering would need
to be updated). Fixed this maintenance burden by using small example
scripts instead of actual Bro scripts. These small example scripts
do not need to be kept in sync with the bro base scripts.
I added the $path to the create_stream() calls inside doc/ as well.
* origin/topic/jsiwek/bit-1324:
Allow logging filters to inherit default path from stream.
BIT-1324: #merged
Removed line numbers in the text because it was difficult to keep these
up-to-date. Changed some wording and moved sample scripts before (rather
than after) the descriptive text in order to keep it easy to understand.
The scope of dns.log is now only standard queries (OPCODE == 0). Other
kinds of queries (e.g. inverse query) were not handled correctly and
could interfere with the state tracking of the default DNS scripts.
Add a "broxygen" domain Sphinx extension w/ directives to allow
on-the-fly documentation to be generated w/ Bro and included in files.
This means all autogenerated reST docs are now done by Bro. The odd
CMake/Python glue scipts which used to generate some portions are now
gone. Bro and the Sphinx extension handle checking for outdated docs
themselves.
Parallel builds of `make doc` target should now work (mostly because
I don't think there's any tasks that can be done in parallel anymore).
Overall, this seems to simplify things and make the Broxygen-generated
portions of the documentation visible/traceable from the main Sphinx
source tree. The one odd thing still is that per-script documentation
is rsync'd in to a shadow copy of the Sphinx source tree within the
build dir. This is less elegant than using the new broxygen extension
to make per-script docs, but rsync is faster and simpler. Simpler as in
less code because it seems like, in the best case, I'd need to write a
custom Sphinx Builder to be able to get that to even work.
* origin/topic/srunnels/documentation:
Spelling corrections.
Include a better description for detect-MHR.bro
Rewrite the MHR detection description.
Spelling corrections.
Update the lines included from events.bif.bro.
I added a better more concise and accurate description of what is going
on behind the scenes of detect-MHR.bro to not only bring it into line
with the Files framework but to help make it a bit more clear as to
where the various responsibilities lie.
Now that the MHR script uses the file analysis framework, the
description needed to be rewritten to reflect the changes. Robin
commented that he didn't feel the MHR script was a good introductory
script and he might be right, however, I couldn't find one that was
easier to explain.
This cleans up most of the warnings from sphinx (broken :doc: links,
broxygen role misuses, etc.). The remaining ones should be harmless,
but not quick to silence.
I found that the README for each component was a copy from the actual
repo, so I turned those in to symlinks so they don't get out of date.
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.
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.
