[Bro-Dev] [JIRA] (BIT-1098) topic/jsiwek/broxygen

[Jon Siwek (JIRA)]

    [ https://bro-tracker.atlassian.net/browse/BIT-1098?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=14914#comment-14914 ] 

Jon Siwek commented on BIT-1098:
--------------------------------

{quote}
- what would you think about moving the global type alias table into BroType as a private static member,  along with a few static accessor methods to manipulate it?
{quote}

Seems better.  Done.

{quote}
- if there's a bro binary in PATH, it seems that "make doc" picks up that one instead of the one in {{src/build/bro}}
{quote}

Fixed.

{quote}
- "make doc" shows {{received termination signal}} right before {{Running Sphinx}}. Is that expected?
{quote}

Expected, I guess.  It's just a result of the broxygen/ package calling {{terminate()}} in {{bro_init()}}.  I do that so that scripts like {{listen.bro}} can be loaded during the doc-generation process.  I don't want to filter all stderr to /dev/null, because that can give useful diagnostics when something goes wrong.  Could grep out just that string, but I'm kind of fine with it...

{quote}
-- I'd remove the "Param" in the function descriptions (or is that a Sphinx thing?)
{quote}

(I think) that was there in the previous Broxygen version, too.  And I think it was only there to make the raw reST output look more like some Python docstring markup.  But I think we're different enough that keep it isn't that beneficial.  So removed.

{quote}
-- If a package has scripts both w/ and wo/ a further description, they appear separately in the package overview; see, e.g., {{scripts/base/frameworks/packet-filter/index.html}}
{quote}

Think I fixed it, or at least made it render consistently.

{quote}
-- should we just omit {{__load__.bro}} in the package overviews?
{quote}

Not sure, but I think it's easiest to just treat them no different than other scripts.  In some cases there might actually be stuff other than {{@load}} in there that would be useful for a person browsing docs (or maybe even having quick access to the set of {{@load}} that is done is useful for quickly switching to other docs).

{quote}
-- I like how the records now show fields that are redefined somewhere else. Two further thoughts: 
--- how about changing {{from redef in XXX}} to {{added if XXX is loaded}}. For a user, it might be more intuitive to talk about loading another script than just redef.
{quote}

Sounds good, changed to {{present if XXX is loaded}}, which seemed clearer that it's referring to the existence of the field.

{quote}
--- for the script that does the redef, can we show the new fields there as well? For example, in {{scripts/policy/protocols/http/software-browser-plugins.bro.html}} it would show not only that {{HTTP::Info}} got redef, but also repeat the fields it added right there. Same for the enums. 
{quote}

Should be technically possible (all the info is tracked), but there'd be some effort setting up new linkage to the doc.  Also not sure how confusing it is to have pieces of the total type put in various places -- right now there's always one canonical place for the full type and there's no duplication of any documentation.  Holding off on doing anything for now.

Updated the /topic/jsiwek/broxygen branch with the changes.



> topic/jsiwek/broxygen
> ---------------------
>
>                 Key: BIT-1098
>                 URL: https://bro-tracker.atlassian.net/browse/BIT-1098
>             Project: Bro Issue Tracker
>          Issue Type: Improvement
>          Components: Bro, Broccoli
>    Affects Versions: git/master
>            Reporter: Jon Siwek
>             Fix For: 2.3
>
>
> This branch is in the bro and broccoli repos and improves the automated script-reference documentation generation process, broxygen.
> This should address issues in BIT-701 and BIT-751, let me know if there's anything not covered that's still relevant.
> Highlights:
> - Remove {{--doc-scripts}} and {{-Z}} options to toggle documentation mode -- the parser is now always instrumented to gather documentation from comments of the form "##", "##!", or "##<".
> - Raw comments are available at runtime through several BIF functions: {{get_*_comments}};
> - Add {{--broxygen}} and {{-X}} options to toggle generating reST-format documentation output, driven by a config file argument.
> - Add a "broxygen" Sphinx extension domain, allowing certain pieces of documentation to be generated on-the-fly via invoking a Bro process.  Re-organized/cleaned up the Sphinx source tree in {{doc/}} to use this in some places.



--
This message was sent by Atlassian JIRA
(v6.2-OD-03#6206)