[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):

 > I have one more request though: can we move ``doc/`` into a subdirectory
 ``doc/scripts/``?

 Yeah, I can do that.

 >  I'm getting a number of `line 1: run-time error: unserialized unknown
 global name` messages when generating the individual reST documents.
 Sounds like  `.state` directory should removed before each run?

 Yeah, I should probably do that.

 >      - During Sphinx' indexing, I'm getting a number of `WARNING:
 unknown document: policy/hot`, `WARNING: unknown document: policy/port-
 name`, etc.

 This is because some policy script loads `hot.bro` and `port-name.bro` and
 the generated reST doc contains the necessary cross-references, but we
 haven't said that we want to include the generated reST docs for `hot.bro`
 or `port-name.bro` in the collection that we use as input for Sphinx, so
 Sphinx just won't render the cross-reference as a hyperlink (you'll still
 get the right text, though).

 The master list of input sources is defined in `generate_reST_docs.py.in`.

 I was struggling somewhat to come up with a good way to organize this
 process, so let me know if you had some other ideas on how/if I can
 improve it.

 > Shouldn't it have the pickled data after the first execution to then run
 faster the next time?

 I made it do a clean before each run because Sphinx was always adding new
 files in the `_downloads` output dir regardless of whether the policy
 script actually changes.  So I was ending up with `alarm.bro`,
 `alarm2.bro`, `alarm3.bro`...

 I'll take a quick look to see if maybe there's some other way I can trick
 it to not do that.

-- 
Ticket URL: <http://tracker.icir.org/bro/ticket/435#comment:4>
Bro Tracker <http://tracker.icir.org/bro>
Bro Issue Tracker