[Bro-Dev] New documentation via Sphinx

[Siwek, Jon]

> On Jul 27, 2016, at 11:22 PM, Matthias Vallentin <vallentin at icir.org> wrote:
> 
>    http://bro.github.io/broker/
> 
> It's the bootstrap theme for sphinx, as an alternative to the classic
> read-the-docs theme. I've hacked the sidebar so that it shows the table
> of contents.

I like that theme/layout.

- The prominent and fully expanded sidebar works well and is more helpful than having to expand them one-by-one when first digging around.

- Having Sphinx auto-add the section numbering makes it easier to understand the doc structure and relationship between sections.

I’ll probably at least use those two design elements in the package manager docs, but maybe worth experimenting w/ other Bro docs to see if it helps there to.

> whole setup looks really simple and could be a good starting point for
> the next Bro documentation overhaul.

I’d also say it could pay off to explore whether it’s better to have each Bro component/submodule be capable of building its own self-contained docs via similar/common Sphinx configurations.  But I’m maybe forgetting a bunch of stuff about how the docs all get glued together when built on bro.org that would make it tricky.

- Jon