[Bro-Dev] #435: topic/jsiwek/doc-framework
Bro Tracker
bro at tracker.icir.org
Mon Apr 18 18:04:35 PDT 2011
#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
More information about the bro-dev
mailing list