[Bro-Dev] New documentation via Sphinx

Matthias Vallentin vallentin at icir.org
Wed Jul 27 21:22:23 PDT 2016


I'm in the process of documenting Broker with Sphinx. With minimal
effort, I put up a scaffold that looks like this:

    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.

The nice thing about this setup is that it doesn't require any
server-side support. I just type `make doc` locally and can open the
HTML pages. I pushed the above to broker's gh-pages branch so that you
can view it under the above github.io URL.

Search is also implemented via JS and works great.

Sphinx also has a plugin to also generate a PDF Version of the manual,
which I've put here: http://docdro.id/rHNvn1X.

Don't look too much at the content, I'm just getting started. But the
whole setup looks really simple and could be a good starting point for
the next Bro documentation overhaul.

    Matthias


More information about the bro-dev mailing list