References to Input::Reader and Log::Writer enum types no longer emit
warnings as they are now hardcoded to be documented as part of their
associated framework scripts and so links to them now work.
- Internals: move type alias table to private static BroType member.
- Sphinx extension: now uses absolute path to bro binary.
- reST ouput formatting: remove "param" from function desriptions
and change package overview docs so script link+summaries render
consistently.
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.
I'm merging in the documentation branch to avoid that it keeps getting
out of sync. We still need to work on this a bit more, I'll summarize
in a mail.
* origin/topic/documentation: (68 commits)
Going over initial parts of the scripting overview.
Adding lines in scripting/index.txt. No other change.
Updating submodule.
Pass over the Using Bro section.
Applying doc updates from BIT-1063. (Anthony Verez)
Breaking lines in using/*.
More doc reorg, and a light pass over the first 3 sections.
Starting to put a new structure in place.
Updating submodule(s).
Updating submodule(s).
Adding some temporary testing/demonstration to front page.
Switching btest to topic/robin/parts branch.
Basic cross-referencing UIDs between files, btests, and baselines.
A truly embarassing number of spelling corrections.
Using redirection with bro-cut. Include initial btests for this document.
Corrected a mis-typed RST include.
Initial start for "Using Bro".
Spelling corrections.
Include Notice Policy shortcuts in the Scripting User Manual.
Notice::policy hooks and tests.
...
Conflicts:
src/3rdparty
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.
It's like ".. literalinclude::" except the argument is an absolute path
which may contain environment variables to be be expanded when
generating documents.
Includes:
- Quite a bit of CSS tweaking.
- Some small changes to BroDoc.cc to change the order of sections.
- A bit of tweaking some reST here and there.
