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.
This is used to display short summaries for things based on the first
sentence in the comments for it, but wouldn't work well when e.g. a
filename is used there.
All tests pass with one exception: some Broxygen tests are broken
because dpd_config doesn't exist anymore. Need to update the mechanism
for auto-documenting well-known ports.
* origin/fastpath:
Enable warnings for malformed Broxygen xref roles.
Broxygen fix for function parameter recognition; better than 80b2451.
Allow Broxygen markup "##<" for more general use.
* origin/fastpath:
Fix missing action in notice policy for looking up GeoIP data.
Better persistent state config warning messages (fixes#433).
A few updates for SQL injection detection.
Fixed some DPD signatures for IRC. Fixes ticket #311.
Removing Off_Port_Protocol_Found notice.
SSH::Interesting_Hostname_Login cleanup. Fixes#664.
Teach Broxygen to more generally reference attribute values by name.
Fixed a really dumb bug that was causing the malware hash registry script to break.
Fix Broxygen confusing scoped id at start of line as function parameter.
Remove remnant of libmagic optionality
- The "private interface" section is still tracked, but no longer rendered.
We can judge the usefulness of it later and add back if there's demand.
- Documentation of event handlers was being treated the same as event
declarations. Now handlers are tracked separately, but not currently
rendered in the generated doc output since usefulness is questionable.
- Log path's are generated in the scripting land
now. The default Log stream ID to path string
mapping works like this:
- Notice::LOG -> "notice"
- Notice::POLICY_LOG -> "notice_policy"
- TestModule::LOG -> "test_module"
- Logging streams updated across all of the shipped
scripts to be more user friendly. Instead of
the logging stream ID HTTP::HTTP, we now have
HTTP::LOG, etc.
- The priorities on some bro_init handlers have
been adjusted to make the process of applying
filters or disabling streams easier for users.
- policy/ renamed to scripts/
- By default BROPATH now contains:
- scripts/
- scripts/policy
- scripts/site
- *Nearly* all tests pass.
- All of scripts/base/ is loaded by main.cc
- Can be disabled by setting $BRO_NO_BASE_SCRIPTS
- Scripts in scripts/base/ don't use relative path loading to ease use of BRO_NO_BASE_SCRIPTS (to copy and paste that script).
- The scripts in scripts/base/protocols/ only (or soon will only) do logging and state building.
- The scripts in scripts/base/frameworks/ add functionality without causing any additional overhead.
- All "detection" activity happens through scripts in scripts/policy/.
- Communications framework modified temporarily to need an environment variable to actually enable (ENABLE_COMMUNICATION=1)
- This is so the communications framework can be loaded as part
of the base without causing trouble when it's not needed.
- This will be removed once a resolution to ticket #540 is reached.
