[Bro-Dev] #751: Broxygen Wishlist

Bro Tracker bro at tracker.bro-ids.org
Wed Jan 11 21:34:31 PST 2012


#751: Broxygen Wishlist
---------------------+--------------------
  Reporter:  robin   |      Owner:
      Type:  Task    |     Status:  new
  Priority:  Normal  |  Milestone:  Bro2.1
 Component:  Bro     |    Version:  2.0
Resolution:          |   Keywords:
---------------------+--------------------
Description changed by robin:

Old description:

> Collecting a number of lower priority items here I noticed:
>

> - In a script's summary section, would be nice if the namespace linked
>   to the corresponding index entry that lists all the scripts
>   contributing to that namespace.
>
> - Thoughts on restructuring the summary section:
>
>     * Notices: Should list the new Notices and link them to a part
>       section in the Detailed Interface that describes them. Probably
>       should then become the first entry of the Summary.
>
>     * Redefinitions: Currently shows the type being modified and the
>       text associated with the new comment, but not the new value
>       itself. Not totally sure how to change, but perhaps just list
>       the ID being modified here and then also link to Detailed
>       INterface section.
>
>     * Redefinitions: That's sometimes hard to understand currently,
>       like in  scripts/base/frameworks/notice/weird.html: It's not
>       that intuitive that Weird::Log is added to Log::ID; and also not
>       what the comment belongs to.
>
>     * Package index: would be nice if it had a brief description of
>       each package, ideally generated automatically somehow (from
>       comments in the __load__.bro perhaps?)
>
> - make -j doesn't work reliably with the doc generation, can give some
>   od errors.
>
> - With all docs in Sphinx now, it would be helpful not have to rebuild
>   everything (including Broxygen) each time one runs "make doc". I
>   remember we discussed using the pickled Sphinx cache before and it
>   didn't seem worth the trouble. May be worth reconsiderng now to keep
>   the rebuild times small when doing just doc/* changes.
>
> - CSS styling the Broxygen part is a bit tricky because it always
>   impacts the rest of the Sphinx-generated content. Is there a way to
>   have a general "broxygen" CSS selector to select only Broxygen
>   items?

New description:

 Collecting a number of lower priority items here I noticed:


 - In a script's summary section, would be nice if the namespace linked
   to the corresponding index entry that lists all the scripts
   contributing to that namespace.

 - Thoughts on restructuring the summary section:
     * Notices: Should list the new Notices and link them to a part in the
 Detailed Interface that describes them.  Could then become the first entry
 of the Summary.
     * Redefinitions: Currently shows the type being modified and the text
 associated with the new comment, but not the new value itself. Not totally
 sure how to change, but perhaps just list the ID being modified here and
 then also link to Detailed INterface section.
     * Redefinitions: That's sometimes hard to understand currently, like
 in  scripts/base/frameworks/notice/weird.html: It's not  that intuitive
 that Weird::Log is added to Log::ID; and also not what the comment belongs
 to.
     * Package index: would be nice if it had a brief description of each
 package, ideally generated automatically somehow (from comments in the
 __load__.bro perhaps?)

 - make -j doesn't work reliably with the doc generation, can give some
   odd errors.

 - With all docs in Sphinx now, it would be helpful not have to rebuild
   everything (including Broxygen) each time one runs "make doc". I
   remember we discussed using the pickled Sphinx cache before and it
   didn't seem worth the trouble. May be worth reconsiderng now to keep
   the rebuild times small when doing just doc/* changes.

 - CSS styling the Broxygen part is a bit tricky because it always
   impacts the rest of the Sphinx-generated content. Is there a way to
   have a general "broxygen" CSS selector to select only Broxygen
   items?

--

-- 
Ticket URL: <http://tracker.bro-ids.org/bro/ticket/751#comment:1>
Bro Tracker <http://tracker.bro-ids.org/bro>
Bro Issue Tracker



More information about the bro-dev mailing list