Added a new section that is intended as a how-to for configuring a Bro
cluster (this section does not discuss cluster architecture or theory)
that is aimed at beginners to Bro. Most of this content was moved here
from the BroControl doc (which is now intended as more of a reference guide
for more experienced users) and the load balancing FAQ on the website.
Renamed the bro cluster doc to better indicate its purpose (it provides
a high-level overview rather than detailed configuration instructions).
Moved the location of the bro cluster doc in the index so that it makes
more sense (it is an introductory section, not a section about using bro).
Added links in the quick start guide and the bro cluster doc so that
readers can more easily locate more detailed information on configuring
a bro cluster.
Addresses BIT-1160
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 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.
