[Bro-Dev] #435: topic/jsiwek/doc-framework
bro at tracker.icir.org
Tue Apr 19 10:51:25 PDT 2011
Reporter: jsiwek | Owner: jsiwek
Type: Task | Status: assigned
Priority: Low | Milestone: Bro1.6
Component: Bro | Version: git/master
Resolution: | Keywords:
Comment (by jsiwek):
> So, once we list everything there, these messages will go away? Then
> Could we delete just the _downloads directory but keep the state?
That would only have the effect of cleaning out _downloads of unused
files, but the latest one will still have a number suffix, e.g. you'd have
an `alarm103.bro` after the 104th run of `make doc`.
But I also realized that's not the only thing holding back the ability to
do incremental builds. In order to get that it to work, I kind of have to
throw away the current version of `make doc` and organize more of it it
inside CMake scripting so I can to teach it how to only generate new reST
when the associated .bro or the `bro` binary itself changes.
I think there's also some extra work to get it to automatically remove
generated reST docs for bro policy scripts that we've removed (either
don't want docs for or just got rid of entirely) -- something that's
easier to do if we just always start clean like it currently does.
> A question: can the doc framework deal with scripts in subdirectories?
The new scripts now do some `@load foo/bar`.
It doesn't -- the cross-referencing link in the docs for the script that
does `@load foo/bar` doesn't point to the right place.
Currently I'm dumping all the generated reST docs into a single flat
directory for Sphinx to process. So a couple options are
1) Just change the link to point to the basename (bar) so that the link is
fixed (the link text still says "foo/bar")
2) Create directory trees for the Sphinx input sources that mimic how the
scripts are `@load`ed.
(1) should be easy, (2) seems more involved. (1) seems ok if we don't
expect to ever have multiple "bar" scripts that reside in different
directories (seems like it would get real confusing if that becomes
What do you think?
Ticket URL: <http://tracker.icir.org/bro/ticket/435#comment:9>
Bro Tracker <http://tracker.icir.org/bro>
Bro Issue Tracker
More information about the bro-dev