- Move notice index wrapper doc to doc/script-reference -- doc/scripts
no longer contains any static documentation because that location
will be managed by Bro to generate per-script docs.
- :doc: references for generated per-script docs now need the ".bro"
suffix. (IMO this is better since it directly mirrors the actual
script's file name and can't be confused w/ a package).
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/dnthayer/doc-changes-for-2.2:
Add gawk to list of optional packages
Add more script package README files
Add NEWS about new features of broctl and upgrade info
BSD and debian-based Linux do not include gawk by default. Noticed
that a test was failing on these platforms due to the use of a bro-cut
option that requires gawk.
Snapshotting the work in this branch. I'll merge it again later as we
get closer to the release.
* origin/topic/dnthayer/doc-changes-for-2.2: (29 commits)
Add README files for base/protocols
Fix incorrect uses of reST directives
Fix typos and formatting in the BiFs docs
Fix typos and formatting in the base/utils docs
Fix typos and formatting in the other protocol docs
Fix typos and formatting in the ssl protocol docs
Fix typos and formatting in the http protocol docs
Fix typos and formatting in the ftp protocol docs
Fix typos and formatting in the dns protocol docs
Fix typos and formatting in the dhcp protocol docs
Adjust line numbers to match changes in conn/main.bro
Fix typos and formatting in the conn protocol docs
Update FreeBSD install instructions
Improvements to file analysis docs
Add README files for most Bro frameworks
Fix typos and formatting in various other framework docs
Fix typos and formatting in the software framework docs
Fix typos and formatting in the sumstats docs
Fix typos and formatting in the packet filter docs
Fix typos and formatting in the logging framework docs
...
* origin/topic/bernhard/input-documentation:
and provide a bit of motivation to try the last example.
and restructure it a bit
First try at sqlite reader/writer documentation
add check that the SQLite reader is only used in MANUAL reading mode
rename the dbname configuration option to tablename.
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.
Added a few missing packages to the install instructions.
Combined the two different sets of GeoIP install instructions into one
location and updated it.
Fixed a couple minor typos.
* 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.
