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
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