Merge pull request #501 from lshamis/master

Adding a section option to the doxygenfile directive

breathe/directive/file.py

@@ -68,12 +68,13 @@ class DoxygenFileDirective(BaseFileDirective):
     directive_name = 'doxygenfile'
 
     required_arguments = 0
-    optional_arguments = 2
+    optional_arguments = 3
     option_spec = {
         "path": unchanged_required,
         "project": unchanged_required,
         "outline": flag,
         "no-link": flag,
+        "sections": unchanged_required,
         }
     has_content = False
 
@@ -100,6 +101,7 @@ class AutoDoxygenFileDirective(BaseFileDirective):
         "project": unchanged_required,
         "outline": flag,
         "no-link": flag,
+        "sections": unchanged_required,
         }
     has_content = False
 

breathe/renderer/sphinxrenderer.py

@@ -584,26 +584,35 @@ def render_signature(file_data, doxygen_target, name, kind):
 
     def visit_compounddef(self, node):
 
-        nodelist = []
-
-        nodelist.extend(self.render_optional(node.briefdescription))
-        nodelist.extend(self.render_optional(node.detaileddescription))
-
-        def render_list(node, prefix):
+        options = self.context.directive_args[2]
+        section_order = None
+        if 'sections' in options:
+            section_order = {sec: i for i, sec in enumerate(options['sections'].split(' '))}
+        nodemap = {}
+
+        def addnode(kind, lam):
+            if section_order is None:
+                nodemap[len(nodemap)] = lam()
+            elif kind in section_order:
+                nodemap.setdefault(section_order[kind], []).extend(lam())
+
+        addnode('briefdescription', lambda: self.render_optional(node.briefdescription))
+        addnode('detaileddescription', lambda: self.render_optional(node.detaileddescription))
+
+        def render_derivedcompoundref(node):
             if node is None:
-                return
+                return []
             output = self.render_iterable(node)
             if not output:
-                return
-            nodelist.append(
-                self.node_factory.paragraph(
-                    '',
-                    '',
-                    self.node_factory.Text(prefix),
-                    *intersperse(output, self.node_factory.Text(', '))
-                )
-            )
-        render_list(node.derivedcompoundref, 'Subclassed by ')
+                return []
+            return [self.node_factory.paragraph(
+                '',
+                '',
+                self.node_factory.Text('Subclassed by '),
+                *intersperse(output, self.node_factory.Text(', '))
+            )]
+
+        addnode('derivedcompoundref', lambda: render_derivedcompoundref(node.derivedcompoundref))
 
         section_nodelists = {}
 
@@ -614,23 +623,28 @@ def render_list(node, prefix):
                 # Skip empty section
                 continue
             kind = sectiondef.kind
+            if section_order is not None and kind not in section_order:
+                continue
             rst_node = self.node_factory.container(classes=['breathe-sectiondef'])
             rst_node.document = self.state.document
             rst_node['objtype'] = kind
             rst_node.extend(child_nodes)
             # We store the nodes as a list against the kind in a dictionary as the kind can be
             # 'user-edited' and that can repeat so this allows us to collect all the 'user-edited'
             # entries together
-            nodes = section_nodelists.setdefault(kind, [])
-            nodes += [rst_node]
+            section_nodelists.setdefault(kind, []).append(rst_node)
 
         # Order the results in an appropriate manner
         for kind, _ in self.sections:
-            nodelist.extend(section_nodelists.get(kind, []))
+            addnode(kind, lambda: section_nodelists.get(kind, []))
 
         # Take care of innerclasses
-        nodelist.extend(self.render_iterable(node.innerclass))
-        nodelist.extend(self.render_iterable(node.innernamespace))
+        addnode('innerclass', lambda: self.render_iterable(node.innerclass))
+        addnode('innernamespace', lambda: self.render_iterable(node.innernamespace))
+
+        nodelist = []
+        for i, nodes_ in sorted(nodemap.items()):
+            nodelist += nodes_
 
         return nodelist
 

documentation/source/file.rst

@@ -21,6 +21,23 @@ It produces this output:
 .. doxygenfile:: nutshell.h
    :project: nutshell
 
+Example with Selected and Ordered Sections
+------------------------------------------
+
+.. cpp:namespace:: @ex_file_section
+
+The following will only show the **briefdescription** and **public-type** sections, in that order.
+
+  .. doxygenfile:: nutshell.h
+     :project: nutshell
+     :sections: briefdescription public-type
+
+----
+
+.. doxygenfile:: nutshell.h
+   :project: nutshell
+   :sections: briefdescription public-type
+
 Example with Nested Namespaces
 ------------------------------