[Bro-Dev] #435: topic/jsiwek/doc-framework

[Bro Tracker]

#435: topic/jsiwek/doc-framework
---------------------+------------------------
  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
 nevermind.

 Yes.

 > 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
 standard practice...).

 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