[Bro-Dev] Broxygen docs

Siwek, Jonathan Luke jsiwek at illinois.edu
Wed Nov 16 12:59:12 PST 2011


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

Ah, yeah.  In a README I think I said you could copy files into the sphinx source tree to get it to render them since that's technically a way to do it.  But the other way I said was just to symlink it and that's the way I currently did it.

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

Ok, good point.  I think that's going to have to be out of the scope of Sphinx/Broxygen.  So we'll have two different ways of rendering "other components":

1) 'www' pulls in certain release revisions of each submodule to render on it's own page
2) 'bro' manages the rendering of submodule READMEs depending on whatever the current submodule pointers are, and then 'www' pulls this in as part of a versioned Bro documentation bundle

+Jon


More information about the bro-dev mailing list