5 Reference count annotations for C API functions. Has the same
6 result as the sphinx.ext.refcounting extension but works for all
7 functions regardless of the signature, and the reference counting
8 information is written inline with the documentation instead of a
11 Adds a new directive "refcounting". The directive has no content
12 and one required positional parameter:: "new" or "borrow".
16 .. cfunction:: json_t *json_object(void)
20 <description of the json_object function>
22 :copyright: Copyright (c) 2009-2012 Petri Lehtinen <petri@digip.org>
23 :license: MIT, see LICENSE for details.
26 from docutils import nodes
28 class refcounting(nodes.emphasis): pass
30 def visit(self, node):
31 self.visit_emphasis(node)
33 def depart(self, node):
34 self.depart_emphasis(node)
36 def html_visit(self, node):
37 self.body.append(self.starttag(node, 'em', '', CLASS='refcount'))
39 def html_depart(self, node):
40 self.body.append('</em>')
43 def refcounting_directive(name, arguments, options, content, lineno,
44 content_offset, block_text, state, state_machine):
45 if arguments[0] == 'borrow':
46 text = 'Return value: Borrowed reference.'
47 elif arguments[0] == 'new':
48 text = 'Return value: New reference.'
50 raise Error('Valid arguments: new, borrow')
52 return [refcounting(text, text)]
55 app.add_node(refcounting,
56 html=(html_visit, html_depart),
57 latex=(visit, depart),
59 app.add_directive('refcounting', refcounting_directive, 0, (1, 0, 0))