Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-05 08:08:19 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1

Teach Broxygen :bro:see: role for referencing any identifier in Bro domain.

Browse source
This commit is contained in:
Jon Siwek 2011-11-17 16:55:51 -06:00
parent ec33453d2d
commit 5227eb73c8
3 changed files with 40 additions and 11 deletions
Download patch file Download diff file Expand all files Collapse all files

27
doc/ext/bro.py
View file

@ -19,6 +19,11 @@ from docutils.parsers.rst import directives
from docutils.parsers.rst.roles import set_classes
class BroGeneric(ObjectDescription):
def update_type_map(self, idname):
if 'idtypes' not in self.env.domaindata['bro']:
self.env.domaindata['bro']['idtypes'] = {}
self.env.domaindata['bro']['idtypes'][idname] = self.objtype
def add_target_and_index(self, name, sig, signode):
targetname = self.objtype + '-' + name
if targetname not in self.state.document.ids:
@ -29,9 +34,6 @@ class BroGeneric(ObjectDescription):
objects = self.env.domaindata['bro']['objects']
key = (self.objtype, name)
# this is commented out mostly just to avoid having a special directive
# for events in order to avoid the duplicate warnings in that case
"""
if key in objects:
self.env.warn(self.env.docname,
'duplicate description of %s %s, ' %
@ -39,8 +41,9 @@ class BroGeneric(ObjectDescription):
'other instance in ' +
self.env.doc2path(objects[key]),
self.lineno)
"""
objects[key] = self.env.docname
self.update_type_map(name)
indextext = self.get_index_text(self.objtype, name)
if indextext:
self.indexnode['entries'].append(('single', indextext,
@ -65,6 +68,8 @@ class BroNamespace(BroGeneric):
objects = self.env.domaindata['bro']['objects']
key = (self.objtype, name)
objects[key] = self.env.docname
self.update_type_map(name)
indextext = self.get_index_text(self.objtype, name)
self.indexnode['entries'].append(('single', indextext,
targetname, targetname))
@ -91,6 +96,8 @@ class BroEnum(BroGeneric):
objects = self.env.domaindata['bro']['objects']
key = (self.objtype, name)
objects[key] = self.env.docname
self.update_type_map(name)
indextext = self.get_index_text(self.objtype, name)
#self.indexnode['entries'].append(('single', indextext,
# targetname, targetname))
@ -140,6 +147,7 @@ class BroDomain(Domain):
'id': XRefRole(),
'enum': XRefRole(),
'attr': XRefRole(),
'see': XRefRole(),
}
initial_data = {
@ -154,6 +162,17 @@ class BroDomain(Domain):
def resolve_xref(self, env, fromdocname, builder, typ, target, node,
contnode):
objects = self.data['objects']
if typ == "see":
if target not in self.data['idtypes']:
self.env.warn(fromdocname,
'unknown target for ":bro:see:`%s`' % (target))
return []
objtype = self.data['idtypes'][target]
return make_refnode(builder, fromdocname,
objects[objtype, target],
objtype + '-' + target,
contnode, target + ' ' + objtype)
else:
objtypes = self.objtypes_for_role(typ)
for objtype in objtypes:
if (objtype, target) in objects:

5
doc/scripts/example.bro
View file

@ -5,6 +5,11 @@
##! (reST) document's summary section.
##!
##! .. tip:: You can embed directives and roles within ``##``-stylized comments.
##!
##! There's also a custom role to reference any identifier node in
##! the Bro Sphinx domain that's good for "see alsos", e.g.
##! "see also :bro:see:`Example::a_var`, :bro:see:`Example::ONE`, and
##! :bro:see:`SSH::Info`"
# Comments that use a single pound sign (#) are not significant to
# a script's auto-generated documentation, but ones that use a

5
testing/btest/Baseline/doc.autogen-reST-example/example.rst
View file

@ -15,6 +15,11 @@ these comments are transferred directly into the auto-generated
.. tip:: You can embed directives and roles within ``##``-stylized comments.
There's also a custom role to reference any identifier node in
the Bro Sphinx domain that's good for "see alsos", e.g.
"see also :bro:see:`Example::a_var`, :bro:see:`Example::ONE`, and
:bro:see:`SSH::Info`"
:Imports: :doc:`policy/frameworks/software/vulnerable </scripts/policy/frameworks/software/vulnerable>`
Summary