Fix doc

[alephzero]

#501

[vermeeren]

We should also document the allowed values for :sections: option. The definitions of sections[] is found at https://github.com/michaeljones/breathe/blob/master/breathe/renderer/sphinxrenderer.py#L546, but this doesn't contain all of the possible values.

For example, at least briefdescription and innerclass are missing from that list. Seems that several nodes are actually manually in visit_compounddef() at https://github.com/michaeljones/breathe/blob/master/breathe/renderer/sphinxrenderer.py#L585.

Do you think that the list is complete is we combine the sections[] list and all addnode('...', ...) names as found invisit_compounddef()? A short description per possible entry should really help out for those trying to use :sections: without knowing the internals.

Probably this needs to be added to the top of documentation/source/file.rst, just like documentation/source/struct.rst has a proper top section with unique options, how to use them and a table of contents.

I could also make these changes if you prefer, but I do need confirmation of the list of possible options before anything can be done by either of us.

[alephzero]

Here's a list of sections I found through experimentation:

• briefdescription
• dcop-func
• define
• derivedcompoundref
• detaileddescription
• enum
• event
• friend
• func
• innerclass
• innernamespace
• package-attrib
• package-func
• package-static-attrib
• package-static-func
• package-type
• private-attrib
• private-func
• private-slot
• private-static-attrib
• private-static-func
• private-type
• property
• protected-attrib
• protected-func
• protected-slot
• protected-static-attrib
• protected-static-func
• protected-type
• prototype
• public-attrib
• public-func
• public-slot
• public-static-attrib
• public-static-func
• public-type
• related
• signal
• typedef
• user-defined
• var

[alephzero]

I haven't been able to find a definitive list anywhere online, or in any doxygen code. This is the closest I've found:
https://github.com/doxygen/doxygen/blob/master/src/xmlgen.cpp#L68

[vermeeren]

Breathe has the following:

briefdescription
dcop-func
define
derivedcompoundref
detaileddescription
enum
event
friend
func
innerclass
innernamespace
package-attrib
package-func
package-static-attrib
package-static-func
package-type
private-attrib
private-func
private-slot
private-static-attrib
private-static-func
private-type
property
protected-attrib
protected-func
protected-slot
protected-static-attrib
protected-static-func
protected-type
prototype
public-attrib
public-func
public-slot
public-static-attrib
public-static-func
public-type
related
signal
typedef
user-defined
var

Doxygen has:

dcop-func
define
dictionary
enum
event
friend
func
interfaces
package-attrib
package-func
package-static-attrib
package-static-func
package-type
private-attrib
private-func
private-slot
private-static-attrib
private-static-func
private-type
property
protected-attrib
protected-func
protected-slot
protected-static-attrib
protected-static-func
protected-type
prototype
public-attrib
public-func
public-slot
public-static-attrib
public-static-func
public-type
related
sequence
services
signal
typedef
var

The output of git diff --no-index doxygen breathe is:

diff --git a/doxygen b/breathe
index 09211c5..ec4e5d3 100644
--- a/doxygen
+++ b/breathe
@@ -1,11 +1,14 @@
+briefdescription
 dcop-func
 define
-dictionary
+derivedcompoundref
+detaileddescription
 enum
 event
 friend
 func
-interfaces
+innerclass
+innernamespace
 package-attrib
 package-func
 package-static-attrib
@@ -32,8 +35,7 @@ public-static-attrib
 public-static-func
 public-type
 related
-sequence
-services
 signal
 typedef
+user-defined
 var

I suppose the things currently in Doxygen but not handled by Breathe are effectively ignored, so it probably makes sense to only document the things actually handled by Breathe. Thanks for the link to Doxygen. I will fixup the doc on this PR in a bit.

[vermeeren]

@alephzero can you check if this looks good to you?

[vermeeren]

@alephzero explicit approve is in the Files changed tab, top-right green button Review changes. You can then approve even without any further comment. Do the other changes look good too, besides the conversation above?

[alephzero]

All changes look good to me! Ship it :)