Merge branch 'membergroups' of https://github.com/ropg/breathe

#637

breathe/directives.py

@@ -246,6 +246,8 @@ class _DoxygenClassLikeDirective(BaseDirective):
         "path": unchanged_required,
         "project": unchanged_required,
         "members": unchanged,
+        "membergroups": unchanged_required,
+        "members-only": flag,
         "protected-members": flag,
         "private-members": flag,
         "undoc-members": flag,

breathe/renderer/sphinxrenderer.py

@@ -971,6 +971,12 @@ def content(contentnode) -> None:
             display_obj_type = 'interface' if kind == 'interface' else None
             nodes = self.handle_declaration(nodeDef, declaration, content_callback=content,
                                             display_obj_type=display_obj_type)
+            if 'members-only' in self.context.directive_args[2]:
+                assert len(nodes) >= 2
+                assert isinstance(nodes[1], addnodes.desc)
+                assert len(nodes[1]) >= 2
+                assert isinstance(nodes[1][1], addnodes.desc_content)
+                return nodes[1][1].children
         return nodes
 
     def visit_namespace(self, node) -> List[Node]:
@@ -1160,6 +1166,9 @@ def visit_compounddef(self, node) -> List[Node]:
         section_order = None
         if 'sections' in options:
             section_order = {sec: i for i, sec in enumerate(options['sections'].split(' '))}
+        membergroup_order = None
+        if 'membergroups' in options:
+            membergroup_order = {sec: i for i, sec in enumerate(options['membergroups'].split(' '))}
         nodemap = {}  # type: Dict[int, List[Node]]
 
         def addnode(kind, lam):
@@ -1168,23 +1177,25 @@ def addnode(kind, 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 []
-            output = self.render_iterable(node)
-            if not output:
-                return []
-            return [nodes.paragraph(
-                '',
-                '',
-                nodes.Text('Subclassed by '),
-                *intersperse(output, nodes.Text(', '))
-            )]
-
-        addnode('derivedcompoundref', lambda: render_derivedcompoundref(node.derivedcompoundref))
+        if 'members-only' not in options:
+            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 []
+                output = self.render_iterable(node)
+                if not output:
+                    return []
+                return [nodes.paragraph(
+                    '',
+                    '',
+                    nodes.Text('Subclassed by '),
+                    *intersperse(output, nodes.Text(', '))
+                )]
+
+            addnode('derivedcompoundref',
+                    lambda: render_derivedcompoundref(node.derivedcompoundref))
 
         section_nodelists = {}  # type: Dict[str, List[Node]]
 
@@ -1193,6 +1204,9 @@ def render_derivedcompoundref(node):
             kind = sectiondef.kind
             if section_order is not None and kind not in section_order:
                 continue
+            header = sectiondef.header
+            if membergroup_order is not None and header not in membergroup_order:
+                continue
             child_nodes = self.render(sectiondef)
             if not child_nodes:
                 # Skip empty section
@@ -1229,13 +1243,18 @@ def render_derivedcompoundref(node):
     section_titles = dict(sections)
 
     def visit_sectiondef(self, node) -> List[Node]:
+        self.context = cast(RenderContext, self.context)
+        options = self.context.directive_args[2]
         node_list = []
         node_list.extend(self.render_optional(node.description))
 
         # Get all the memberdef info
         node_list.extend(self.render_iterable(node.memberdef))
 
         if node_list:
+            if 'members-only' in options:
+                return node_list
+
             text = self.section_titles[node.kind]
             # Override default name for user-defined sections. Use "Unnamed
             # Group" if the user didn't name the section

documentation/source/class.rst

@@ -6,8 +6,8 @@ doxygenclass Directive
 
 This directive generates the appropriate output for a single class. It takes the
 standard ``project``, ``path``, ``outline`` and ``no-link`` options and
-additionally the ``members``, ``protected-members``, ``private-members`` and
-``undoc-members`` options.
+additionally the ``members``, ``protected-members``, ``private-members``,
+``undoc-members``, ``membergroups`` and ``members-only`` options.
 
 ``members``
    Designed to behavior in a similar manner to the ``members`` option for the
@@ -29,6 +29,14 @@ additionally the ``members``, ``protected-members``, ``private-members`` and
 ``undoc-members``
    If specified, the undocumented members of the class will be displayed.
 
+``membergroups``
+  If specified, only the groups in a space-delimited list following this
+  directive will be displayed.
+
+``members-only``
+  This will allow to show only the members, not the class information. Child
+  classes and structs are also not shown.
+
 If you would like to always specify some combination of ``members``,
 ``protected-members``, ``private-members`` and ``undoc-members`` then you can
 use the :ref:`breathe_default_members <breathe-default-members>` configuration
@@ -206,6 +214,98 @@ It produces this output:
    Undocumented classes are still not shown in the output due to an implementation
    issue. Please post an issue on github if you would like this resolved.
 
+
+.. _class-example-membergroups:
+
+Membergroups
+------------
+
+.. cpp:namespace:: @ex_class_membergroups
+
+This will show only members in the specified member group(s).
+
+.. code-block:: rst
+
+   .. doxygenclass:: GroupedMembers
+      :project: membergroups
+      :members:
+      :membergroups: myGroup
+
+It produces this output:
+
+.. doxygenclass:: GroupedMembers
+   :project: membergroups
+   :members:
+   :membergroups: myGroup
+
+Without ``:membergroups: myGroup`` it would produce:
+
+.. doxygenclass:: GroupedMembers
+   :project: membergroups
+   :members:
+
+
+.. _class-example-membersonly:
+
+Members-only
+------------
+
+.. cpp:namespace:: @ex_class_members_only
+
+This will only show the members of a class, and not the class name, child
+classes or structs, or any information about the class.
+
+.. code-block:: rst
+
+   .. doxygenclass:: ClassTest
+      :project: class
+      :members:
+      :members-only:
+
+It produces this output:
+
+.. doxygenclass:: ClassTest
+   :project: classtest
+   :members:
+   :members-only:
+
+Without ``:members-only:`` it would produce:
+
+.. doxygenclass:: ClassTest
+   :project: classtest
+   :members:
+
+.. note::
+
+   The members will be shown at the indentation normally reserver for class
+   definitions. To prevent this, you may want to indent the block by indenting
+   the ``.. doxygenclass`` directive.
+
+.. note::
+
+   In the ``readthedocs`` theme, the members will show up in the color scheme of the
+   class definitions. If you would like them rendered as the other members,
+   indent like above, create a ``_static/css/custom.css`` file containing
+
+   .. code-block:: css
+
+      /* render as functions not classes when indented (for :members-only:) */
+      html.writer-html4 .rst-content blockquote dl:not(.field-list)>dt, html.writer-html5 .rst-content blockquote dl[class]:not(.option-list):not(.field-list):not(.footnote):not(.glossary):not(.simple)>dt {
+        margin-bottom: 6px;
+        border: none;
+        border-left: 3px solid #ccc;
+        background: #f0f0f0;
+        color: #555;
+      }
+
+   and add the following to your ``conf.py``
+
+   .. code-block:: python
+
+      html_static_path = ['_static']
+      
+      html_css_files = ['css/custom.css']
+
 Outline Example
 ---------------
 

documentation/source/conf.py

@@ -119,7 +119,7 @@
 
 
 # Configuration for mathjax extension
-# 
+#
 # Set path for mathjax js to a https URL as sometimes the Breathe docs are displayed under https
 # and we can't load an http mathjax file from an https view of the docs. So we change to a https
 # mathjax file which we can load from http or https. We break the url over two lines.
@@ -224,6 +224,7 @@
     "cpp_inherited_members":"../../examples/specific/cpp_inherited_members/xml/",
     "cpp_trailing_return_type":"../../examples/specific/cpp_trailing_return_type/xml/",
     "xrefsect": "../../examples/specific/xrefsect/xml/",
+    "membergroups": "../../examples/specific/membergroups/xml/",
     }
 
 breathe_projects_source = {

documentation/source/directives.rst

@@ -70,8 +70,8 @@ doxygenclass
 
 This directive generates the appropriate output for a single class. It takes the
 standard ``project``, ``path``, ``outline`` and ``no-link`` options and
-additionally the ``members``, ``protected-members``, ``private-members`` and
-``undoc-members`` options::
+additionally the ``members``, ``protected-members``, ``private-members``,
+``undoc-members``, ``membergroups`` and ``members-only`` options::
 
    .. doxygenclass:: <class name>
       :project: ...
@@ -80,6 +80,8 @@ additionally the ``members``, ``protected-members``, ``private-members`` and
       :protected-members:
       :private-members:
       :undoc-members:
+      :membergroups: ...
+      :members-only:
       :outline:
       :no-link:
 
@@ -300,8 +302,8 @@ This directive generates the appropriate output for a single struct. The struct
 name is required to be unique in the project.
 
 It takes the standard ``project``, ``path``, ``outline`` and ``no-link`` options
-and additionally the ``members``, ``protected-members``, ``private-members`` and
-``undoc-members`` options.
+and additionally the ``members``, ``protected-members``, ``private-members``,
+``membergroups``, ``members-only`` and ``undoc-members`` options.
 
 ::
 
@@ -312,6 +314,8 @@ and additionally the ``members``, ``protected-members``, ``private-members`` and
       :protected-members:
       :private-members:
       :undoc-members:
+      :membergroups: ...
+      :members-only:
       :outline:
       :no-link:
 
@@ -333,6 +337,8 @@ class). It behaves the same as the doxygenclass directive.
       :protected-members:
       :private-members:
       :undoc-members:
+      :membergroups: ...
+      :members-only:
       :outline:
       :no-link:
 

documentation/source/struct.rst

@@ -8,8 +8,8 @@ doxygenstruct Directive
 
 This directive generates the appropriate output for a single struct. It takes the
 standard ``project``, ``path``, ``outline`` and ``no-link`` options and
-additionally the ``members``, ``protected-members``, ``private-members`` and
-``undoc-members`` options.
+additionally the ``members``, ``protected-members``, ``private-members``,
+``undoc-members``, ``membergroups`` and ``members-only`` options.
 
 ``members``
    Designed to behavior in a similar manner to the ``members`` option for the
@@ -31,6 +31,14 @@ additionally the ``members``, ``protected-members``, ``private-members`` and
 ``undoc-members``
    If specified, the undocumented members of the struct will be displayed.
 
+``membergroups``
+  If specified, only the groups in a space-delimited list following this
+  directive will be displayed.
+
+``members-only``
+  This will allow to show only the members, not the struct information. Child
+  classes and structs are also not shown.
+
 If you would like to always specify some combination of ``members``,
 ``protected-members``, ``private-members`` and ``undoc-members`` then you can
 use the :ref:`breathe_default_members <breathe-default-members>` configuration
@@ -171,7 +179,23 @@ It produces this output:
 
    Undocumented internal classes are still not shown in the output due to an
    implementation issue. Please post an issue on github if you would like this
-   resolved.  
+   resolved.
+
+
+Membergroups
+------------
+
+.. cpp:namespace:: @ex_struct_membersgroups
+
+Lists one or more names member groups.
+
+See the :ref:`doxygenclass documentation <class-example-membergroups>`.
+
+
+Members-only
+------------
+
+See the :ref:`doxygenclass documentation <class-example-membersonly>`.
 
 
 Outline Example

examples/specific/Makefile

@@ -26,7 +26,7 @@ projects  = nutshell alias rst inline namespacefile array inheritance \
 			enum define interface xrefsect tables \
 			cpp_anon cpp_enum cpp_union cpp_function cpp_friendclass \
 			cpp_inherited_members cpp_trailing_return_type \
-			c_file c_struct c_enum c_typedef c_macro c_union
+			c_file c_struct c_enum c_typedef c_macro c_union membergroups
 
 special   = programlisting decl_impl multifilexml auto class typedef
 

examples/specific/membergroups.cfg

@@ -0,0 +1,11 @@
+PROJECT_NAME     = "Member Groups"
+OUTPUT_DIRECTORY = membergroups
+GENERATE_LATEX   = NO
+GENERATE_MAN     = NO
+GENERATE_RTF     = NO
+CASE_SENSE_NAMES = NO
+INPUT            = membergroups.h
+QUIET            = YES
+JAVADOC_AUTOBRIEF = YES
+GENERATE_HTML = NO
+GENERATE_XML = YES

examples/specific/membergroups.h

@@ -0,0 +1,13 @@
+//! \brief demonstrates member groups
+class GroupedMembers {
+
+public:
+
+    ///@{   @name myGroup
+    void in_mygroup_one(int myParameter);  ///< A function
+    void in_mygroup_two(int myParameter);  ///< Another function
+    ///@}
+
+    void not_in_mygroup(int myParameter);  ///< This one is not in myGroup
+
+};