[Bro-Dev] Broxygen docs

Robin Sommer robin at icir.org
Wed Nov 16 12:39:40 PST 2011


On Wed, Nov 16, 2011 at 19:44 +0000, you wrote:

> I think I'm not foreseeing the same process that you are.

I may have just misunderstood how things are done currently. I didn't
really look at it yet but thought I saw somewhere a comment about
having to copy files over manually. Discard my concern if that's not
the case.

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

Even with this model (which is generally fine with me) we'll have one
issue: the submodule docs will reflect whatever the specific revision
is that the Bro supermodule pulls in. That's kind of right from the
supermodule's perspective as that's what that version of the
supermodule is using. But on www, we also list the modules separately
and may want to document different versions there. Say we do a Bro
release. The Bro docs are then frozen at that point and will show up
on www/documentation. However, if we then did an intermediary Broccoli
release, the Bro docs would keep showing the old version. Is there a
way to avoid that when having the submodule docs in Sphinx as well?

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

Yes, that's my vision as well (or at least "replace *most* of the
current doc directory" depending on how we decide to handle the
submodules, per above).

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

That would great, yes.

(www is starting to intimidate me as well as it's getting quite
complex; moving more into Sphinx should help with that as well.
Generally, if you find opportunity to clean things up or make simpler,
feel free to go ahead. My main objective with www is just to keep
things as automated as possible so that when we're doing updates to
any of the repos, one doesn't always need to remember to go to www and
do certain things there as well. That's where some of the complexity
is coming from.).

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

Thanks (but leaving things like this at lower priority is fine).

Robin

-- 
Robin Sommer * Phone +1 (510) 722-6541 * robin at icir.org
ICSI/LBNL    * Fax   +1 (510) 666-2956 *   www.icir.org


More information about the bro-dev mailing list