[Bro-Dev] Broxygen docs

Siwek, Jonathan Luke jsiwek at illinois.edu
Wed Nov 16 11:44:30 PST 2011


>    - I think we should leave the "other components" out and document
>      them separately on the web page.

By letting Broxygen handle rendering of "other components", it seems to me that it makes it easier from a "documentation bundling" perspective in that you'll always get the component documentation that's associated with a given bro repo commit.

> That stuff is pulled out of the
>      other git repositories, and doing that manually (as I think one
>      would have to, right?) is quite cumbersome and error prone.

I think I'm not foreseeing the same process that you are.  If 'www' delegates the rendering of "other components" to the 'bro' repo and that gets linked on the Broxygen main index, then all 'www' has to do is grab the 'html' output as a whole.  Currently, there's nothing manual about getting Broxygen to render the correct "other components" because they're just symlinks into git submodules.

> 
>    - The changes break the current web pages unfortunately, see:
> 
>        http://www.bro-ids.org/documentation-beta/index.html
>        http://www.bro-ids.org/documentation-git/index.html
> 
>      We should be able to hard-code the beta page to the last commit
>      before the merge, and can then keep working on the git version.

Yeah, I was kind of hoping for the Broxygen docs to completely replace the current documentation*/ directories.  I mean you'd still have different versions of documentation but each one would be obtained my doing `make broxygen` for a particular commit in a 'bro' repo.

Depending on your response to above issues, want me to take a shot ('www' intimidates me sometimes) at inserting the Broxygen docs?

>    - I suggest to use the non-serif font for the section headlines,
>      and using serif only for the page title. That's how the web
>      pages are doing as well and looks a bit better IMO.

Ok.  I think I saw a couple other style differences I can try to hunt down.

+Jon




More information about the bro-dev mailing list