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.
To do this, the document root and autogenerated bro script docs
are rsync'd in to Sphinx's working directory instead of a plain
recursive copy. There are still some index files that are auto
generated on each build and will trigger Sphinx to re-build them
since it thinks they changed, but overall the build is much faster
this way.
One limitation of this is that old files in the Sphinx work dir
don't automatically get cleaned up (e.g. if you remove some static
documentation from the /doc it will still be in
build/doc/sphinx-sources). So a `make docclean` or at least
`make broxygenclean` is needed at least in that case. (For now,
rsync --delete isn't the right answer since the destination of
the autogenerated stuff overlaps with the document root, the separate
rsyncs end up clobbering each other.)
- 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.
