Permalink
Browse files

Update breathe to new version that supports referencing function dire…

…ctives
  • Loading branch information...
1 parent 6ed5496 commit 22d5b5bc31c1d44d271c9e096510e2e9a13abb25 @nzjrs committed Jun 4, 2009
Showing with 239 additions and 25 deletions.
  1. +1 −0 .gitignore
  2. +6 −0 conf.py
  3. +2 −1 doc/.gitignore
  4. +109 −7 doc/breathe/__init__.py
  5. +79 −15 doc/breathe/doxparsers/compound.py
  6. +26 −0 doc/breathe/doxparsers/index.py
  7. +8 −0 index.rst
  8. +7 −0 sw/test/tinyxml.h
  9. +1 −2 sw/test/tinyxml.rst
View
@@ -0,0 +1 @@
+*.pyc
View
@@ -90,6 +90,12 @@
# A list of ignored prefixes for module index sorting.
#modindex_common_prefix = []
+# -- Options for breath doxygen bridge ---------------------------------------------------
+
+breathe_projects = {
+ "tinyxml":"doc/built/tinyxml/xml/"
+}
+breathe_default_project = "tinyxml"
# -- Options for HTML output ---------------------------------------------------
View
@@ -1,2 +1,3 @@
+built
html
-doctrees
+.doctrees
@@ -3,30 +3,127 @@
from docutils.parsers.rst.directives import unchanged_required
import os
+import sys
+import copy
from docutils.parsers import rst
import breathe.doxparsers.index
import breathe.doxparsers.compound
+class ElementDescription(object):
+
+ def __init__(self, name, kind):
+ self.name = name
+ self.kind = kind
+
+
+class DoxygenBase(object):
+
+ def get_path(self):
+
+ index_path = DoxygenBase.projects[ DoxygenBase.default_project ]
+
+ if self.options.has_key("project"):
+ try:
+ index_path = DoxygenBase.projects[ self.options["project"] ]
+ except KeyError, e:
+ sys.stderr.write(
+ "Unable to find project '%s' in breathe_projects dictionary" % self.options["project"]
+ )
+
+ if self.options.has_key("path"):
+ index_path = self.options["path"]
+
+ return index_path
+
+
+
# Directives
# ----------
-class DoxygenIndexDirective(rst.Directive):
+class DoxygenIndexDirective(rst.Directive, DoxygenBase):
required_arguments = 0
+ optional_arguments = 2
+ option_spec = {
+ "path" : unchanged_required,
+ "project" : unchanged_required,
+ }
+ has_content = False
+
+ def run(self):
+
+ index_path = self.get_path()
+
+ index_file = os.path.join(index_path, "index.xml")
+
+ root_object = doxparsers.index.parse( index_file )
+
+ return root_object.rst_nodes(index_path)
+
+
+class DoxygenFunctionDirective(rst.Directive, DoxygenBase):
+
+ required_arguments = 1
optional_arguments = 1
- option_spec = { "path" : unchanged_required }
+ option_spec = {
+ "path" : unchanged_required,
+ "project" : unchanged_required,
+ }
has_content = False
def run(self):
- path = self.options["path"]
+ function_name = self.arguments[0]
- index_file = os.path.join(path, "index.xml")
+ index_path = self.get_path()
+ index_file = os.path.join(index_path, "index.xml")
root_object = doxparsers.index.parse( index_file )
- return root_object.rst_nodes(path)
+ # Find function in the index file
+ details = ElementDescription(name=function_name, kind="function")
+ results = root_object.find_compounds_and_members( details )
+
+ if not results:
+ warning = 'doxygenfunction: Cannot find function "%s" in doxygen xml output' % function_name
+ return [ nodes.warning( "", nodes.paragraph("", "", nodes.Text(warning))),
+ self.state.document.reporter.warning( warning, line=self.lineno) ]
+
+ objects = []
+
+ # Find functions in files suggested by index
+ for entry in results:
+
+ ref_xml_path = os.path.join( index_path, "%s.xml" % entry[0].refid )
+ root_object = breathe.doxparsers.compound.parse( ref_xml_path )
+
+ for memberdef in entry[1]:
+
+ criteria = copy.deepcopy(details)
+ criteria.refid = memberdef.refid
+
+ objects.append(root_object.find(criteria))
+
+ if not objects:
+ warning = 'doxygenfunction: Cannot find %s in doxygen xml output' % function_name
+ return [ self.state.document.reporter.warning( warning, line=self.lineno) ]
+
+ elif len( objects ) > 1:
+ warning = 'doxygenfunction: Found multiple matches for "%s" in doxygen xml output.' % function_name
+ warning += ' Please be more specific.'
+ return [ self.state.document.reporter.warning( warning, line=self.lineno) ]
+
+
+ return objects[0].rst_nodes()
+
+
+
+def get_config_values(app):
+
+ DoxygenBase.projects = app.config.breathe_projects
+ DoxygenBase.default_project = app.config.breathe_default_project
+
# Setup
# -----
@@ -38,8 +135,13 @@ def setup(app):
DoxygenIndexDirective,
)
- app.add_config_value("breathe_path", [], True)
-
+ app.add_directive(
+ "doxygenfunction",
+ DoxygenFunctionDirective,
+ )
+ app.add_config_value("breathe_projects", {}, True)
+ app.add_config_value("breathe_default_project", "", True)
+ app.connect("builder-inited", get_config_values)
@@ -21,6 +21,10 @@ def rst_nodes(self):
# Only interested in the compounddef child node
return self.compounddef.rst_nodes()
+ def find(self, details):
+
+ return self.compounddef.find(details)
+
supermod.DoxygenType.subclass = DoxygenTypeSub
# end class DoxygenTypeSub
@@ -29,18 +33,50 @@ class compounddefTypeSub(supermod.compounddefType):
def __init__(self, kind=None, prot=None, id=None, compoundname='', title='', basecompoundref=None, derivedcompoundref=None, includes=None, includedby=None, incdepgraph=None, invincdepgraph=None, innerdir=None, innerfile=None, innerclass=None, innernamespace=None, innerpage=None, innergroup=None, templateparamlist=None, sectiondef=None, briefdescription=None, detaileddescription=None, inheritancegraph=None, collaborationgraph=None, programlisting=None, location=None, listofallmembers=None):
supermod.compounddefType.__init__(self, kind, prot, id, compoundname, title, basecompoundref, derivedcompoundref, includes, includedby, incdepgraph, invincdepgraph, innerdir, innerfile, innerclass, innernamespace, innerpage, innergroup, templateparamlist, sectiondef, briefdescription, detaileddescription, inheritancegraph, collaborationgraph, programlisting, location, listofallmembers)
- titles = {
- "public-func": "Public Functions",
- "private-func": "Private Functions",
- "public-attrib": "Public Members",
- "private-attrib": "Private Members",
- }
-
- def extend_nodelist(self, nodelist, section, section_nodelists):
+ section_titles = [
+ ("user-defined", "User Defined"),
+ ("public-type", "Public Type"),
+ ("public-func", "Public Functions"),
+ ("public-attrib", "Public Members"),
+ ("public-slot", "Public Slot"),
+ ("signal", "Signal"),
+ ("dcop-func", "DCOP Function"),
+ ("property", "Property"),
+ ("event", "Event"),
+ ("public-static-func", "Public Static Functons"),
+ ("public-static-attrib", "Public Static Attributes"),
+ ("protected-type", "Protected Types"),
+ ("protected-func", "Protected Functions"),
+ ("protected-attrib", "Protected Attributes"),
+ ("protected-slot", "Protected Slots"),
+ ("protected-static-func", "Protected Static Functions"),
+ ("protected-static-attrib", "Protected Static Attributes"),
+ ("package-type", "Package Types"),
+ ("private-func", "Private Functions", "Private Functions"),
+ ("package-attrib", "Package Attributes"),
+ ("package-static-func", "Package Static Functions"),
+ ("package-static-attrib", "Package Static Attributes"),
+ ("private-type", "Private Types"),
+ ("private-func", "Private Functions"),
+ ("private-attrib", "Private Members"),
+ ("private-slot", "Private Slots"),
+ ("private-static-func", "Private Static Functions"),
+ ("private-static-attrib", "Private Static Attributes"),
+ ("friend", "Friends"),
+ ("related", "Related"),
+ ("define", "Defines"),
+ ("prototype", "Prototypes"),
+ ("typedef", "Typedefs"),
+ ("enum", "Enums"),
+ ("func", "Functions"),
+ ("var", "Variables"),
+ ]
+
+ def extend_nodelist(self, nodelist, section, title, section_nodelists):
# Add title and contents if found
if section_nodelists.has_key(section):
- nodelist.append(nodes.emphasis(text=self.titles[section]))
+ nodelist.append(nodes.emphasis(text=title))
nodelist.append(nodes.block_quote("", *section_nodelists[section]))
@@ -56,13 +92,21 @@ def rst_nodes(self):
nodelist = []
# Order the results in an appropriate manner
- self.extend_nodelist(nodelist, "public-func", section_nodelists)
- self.extend_nodelist(nodelist, "private-func", section_nodelists)
- self.extend_nodelist(nodelist, "public-attrib", section_nodelists)
- self.extend_nodelist(nodelist, "private-attrib", section_nodelists)
+ for entry in self.section_titles:
+ self.extend_nodelist(nodelist, entry[0], entry[1], section_nodelists)
+
+ self.extend_nodelist(nodelist, "", "", section_nodelists)
return [nodes.block_quote("", *nodelist)]
+ def find(self, details):
+
+ for sectiondef in self.sectiondef:
+ result = sectiondef.find(details)
+ if result:
+ return result
+
+
supermod.compounddefType.subclass = compounddefTypeSub
# end class compounddefTypeSub
@@ -141,6 +185,14 @@ def rst_nodes(self):
# Return with information about which section this is
return self.kind, [def_list]
+ def find(self, details):
+
+ for memberdef in self.memberdef:
+ if memberdef.id == details.refid:
+ return memberdef
+
+ return None
+
supermod.sectiondefType.subclass = sectiondefTypeSub
# end class sectiondefTypeSub
@@ -168,9 +220,9 @@ def rst_nodes(self):
# Get the function arguments
args.append(nodes.Text("("))
- for parameter in self.param:
+ for i, parameter in enumerate(self.param):
+ if i: args.append(nodes.Text(", "))
args.extend(parameter.rst_nodes())
- args.append(nodes.Text(", "))
args.append(nodes.Text(")"))
term = nodes.term("","", *args)
@@ -240,6 +292,18 @@ def rst_nodes(self):
nodelist.extend(kind)
+ # Parameter name
+ if self.declname:
+ nodelist.append(nodes.Text(self.declname))
+
+ if self.defname:
+ nodelist.append(nodes.Text(self.defname))
+
+ # Default value
+ if self.defval:
+ nodelist.append(nodes.Text(" = "))
+ nodelist.extend(self.defval.rst_nodes())
+
return nodelist
supermod.paramType.subclass = paramTypeSub
@@ -27,6 +27,19 @@ def rst_nodes(self, path):
return nodelist
+ def find_compounds_and_members(self, details):
+ """
+ Returns a list of all compounds and their members which match details
+ """
+
+ results = []
+ for compound in self.compound:
+ members = compound.find_members(details)
+ if members:
+ results.append([compound, members])
+
+ return results
+
supermod.DoxygenType.subclass = DoxygenTypeSub
# end class DoxygenTypeSub
@@ -50,6 +63,19 @@ def rst_nodes(self, path):
return nodelist
+ def find_members(self, details):
+ """
+ Returns a list of all members which match details
+ """
+
+ results = []
+
+ for member in self.member:
+ if member.name == details.name and member.kind == details.kind:
+ results.append(member)
+
+ return results
+
supermod.CompoundType.subclass = CompoundTypeSub
# end class CompoundTypeSub
View
@@ -13,3 +13,11 @@ Documentation
sw/doc/autopilot
sw/test/tinyxml
+doxygenfunction Directive Tests
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+This should work.
+
+.. doxygenfunction:: frobnicate
+ :project: tinyxml
+
View
@@ -1770,6 +1770,13 @@ class TiXmlPrinter : public TiXmlVisitor
TIXML_STRING lineBreak;
};
+/** Frobnicates rapidly.
+
+ \param a Your mum
+ \param c me
+*/
+char *frobnicate(int a, char c);
+
#ifdef _MSC_VER
#pragma warning( pop )
View
@@ -2,8 +2,7 @@
TinyXML Test Suite
==================
-
.. doxygenindex::
- :path: doc/built/tinyxml/xml
+ :project: tinyxml

0 comments on commit 22d5b5b

Please sign in to comment.