librelist archives

« back to archive

Class Linking in Breathe

Class Linking in Breathe

From:
Patrick Cieplak
Date:
2012-11-15 @ 16:47
All,

Thank you all very much for the Breathe project.   We have been using
Breathe with much success on a large C++ project.

There does not seem to be a way to link to classes.  I'm not sure if this
feature is supported.  You can see this if you click on any of the links to
the Nutshell class on this page:

http://michaeljones.github.com/breathe/#nutshellclass_nutshell

Is this something that hasn't been implemented, or is it a bug?

If you look at the MemberDefTypeSubRenderer class in the compound.py file (

https://github.com/michaeljones/breathe/blob/master/breathe/renderer/rst/doxygen/compound.py),
 you can see that there are methods create_target and create domain_id.  It
seems that these methods are responsible for rendering the links and link
targets for various class members using the refid values from the Doxygen.
 The CompoundDefTypeSubRenderer class does not have these methods.  In the
doxygen xml, the class name comes in on the compounddef node, which in turn
contains the memberdef nodes, which contain information about the class
members.  Linking works great for the class members, just not the classes
themselves.

If it is the case that class linking hasn't been implemented, what is the
most consistent way to implement this feature?  Would it be best to
implement the create_target and create_domain_id methods on the
CompoundDefTypeSubRenderer class?

Thanks,
Patrick

Re: [breathe] Class Linking in Breathe

From:
Michael Jones
Date:
2012-11-16 @ 06:19
Hi Patrick,

Thank you for using Breathe.  I've very happy to hear it is (mostly)
working well for you :)  Especially if it is a large project as I've not
put much effort into seeing how the code scales on larger code bases.

I honestly thought this functionality worked.  I'd have to look closer to
see what has gone wrong.  Thank you for the thorough break down, if you're
interested in contributing I'd be very happy for you to have a go but I'm
afraid it has been sufficiently long since I worked with that part of the
code that I've forgotten the details.  I've got a busy weekend ahead of me
but I'd be happy to look next week.

I think the class name is created by the *CompoundTypeSubRenderer* class in
the *index.py* file in that *render/rst/doxygen* folder.  That does seem to
be making an effort to create the target but it seems to be failing for
some reason.  Some of the examples in the docs use the *no-link* option to
stop the creation of the targets otherwise Sphinx gets confused if the same
examples and targets are created in multiple parts of the same project, but
I think the Nutshell example should work.

Not sure why it isn't working, but please investigate if you are
interested, otherwise I will next week.

Thanks again for the report,
Michael



On Fri, Nov 16, 2012 at 5:47 AM, Patrick Cieplak
<patrick.cieplak@gmail.com>wrote:

> All,
>
> Thank you all very much for the Breathe project.   We have been using
> Breathe with much success on a large C++ project.
>
> There does not seem to be a way to link to classes.  I'm not sure if this
> feature is supported.  You can see this if you click on any of the links to
> the Nutshell class on this page:
>
> http://michaeljones.github.com/breathe/#nutshellclass_nutshell
>
> Is this something that hasn't been implemented, or is it a bug?
>
> If you look at the MemberDefTypeSubRenderer class in the compound.py
> file (
> 
https://github.com/michaeljones/breathe/blob/master/breathe/renderer/rst/doxygen/compound.py),
>  you can see that there are methods create_target and create domain_id.  It
> seems that these methods are responsible for rendering the links and link
> targets for various class members using the refid values from the Doxygen.
>  The CompoundDefTypeSubRenderer class does not have these methods.  In
> the doxygen xml, the class name comes in on the compounddef node, which in
> turn contains the memberdef nodes, which contain information about the
> class members.  Linking works great for the class members, just not the
> classes themselves.
>
> If it is the case that class linking hasn't been implemented, what is the
> most consistent way to implement this feature?  Would it be best to
> implement the create_target and create_domain_id methods on the
> CompoundDefTypeSubRenderer class?
>
> Thanks,
> Patrick
>

Re: [breathe] Class Linking in Breathe

From:
Patrick Cieplak
Date:
2012-11-20 @ 14:25
Hi Michael,

I was able to kludge it into working last week, but I think I'm doing it
the wrong way.  I've pasted in the patches to this email, because I
couldn't send the email to the mailing list with an attachment.  If there
are issues with this, I could email the patches directly.

*sphinx/exts/breathe/breathe/renderer/rst/doxygen/domain.py*

@@ -108,12 +108,15 @@
 class CppDomainHandler(DomainHandler):

     def create_class_id(self, data_object):
-
-        def_ = data_object.name
-
+
+        try:
+            def_ = data_object.name
+        except:
+            def_ = data_object.compoundname
+        print dir(data_object)
         parser = self.helper.definition_parser(def_)
         sigobj = parser.parse_class()
-
+
         return sigobj.get_id()

     def create_class_target(self, data_object):
@@ -133,7 +136,11 @@
         signode["names"].append(_id)
         signode["ids"].append(_id)

-        name = data_object.name
+        try:
+            name = data_object.name
+        except:
+            name = data_object.compoundname
+

 self.document.settings.env.domaindata['cpp']['objects'].setdefault(name,
                 (self.document.settings.env.docname, "class", _id))


*sphinx/exts/breathe/breathe/renderer/rst/doxygen/compound.py*


@@ -14,6 +14,31 @@



 class CompoundDefTypeSubRenderer(Renderer):



+    def create_target(self, refid):

+

+#        self.domain_handler.create_class_target(self.data_object)

+        self.current_increment += 1

+        return self.target_handler.create_target(refid +
str(self.current_increment))

+

+    def create_domain_id(self):

+

+        return self.domain_handler.create_class_id(self.data_object)

+

+    def title(self):

+

+        kind = []

+

+        name = self.node_factory.strong(text=self.data_object.compoundname)

+

+        args = []

+        args.extend(kind)

+        args.extend([self.node_factory.Text(" "), name])

+

+        return args

+

+

+

+

     section_titles = [

                 "user-defined",

                 "public-type",

@@ -56,6 +81,21 @@



         nodelist = []



+        refid = "%s%s" % (self.project_info.name(), self.data_object.id)

+        domain_id = self.create_domain_id()

+#        print "refid : " + refid

+#        print "domain_id : " + domain_id

+#

+        title = self.title()

+        target = self.create_target(refid)

+#        target.extend(title)

+        term = self.node_factory.paragraph("", "", ids=[domain_id,refid],
*target )

+

+

+        if self.data_object.compoundname:

+#            renderer =
self.renderer_factory.create_renderer(self.data_object,
self.data_object.compoundname)

+            nodelist.append(self.node_factory.block_quote("", term))

+

         if self.data_object.briefdescription:

             renderer =
self.renderer_factory.create_renderer(self.data_object,
self.data_object.briefdescription)

             nodelist.append(self.node_factory.paragraph("", "",
*renderer.render()))


*sphinx/exts/breathe/breathe/renderer/rst/doxygen/base.py*


@@ -20,5 +20,5 @@

         self.document = document

         self.domain_handler = domain_handler

         self.target_handler = target_handler

+        self.current_increment = 0



-



On Fri, Nov 16, 2012 at 1:19 AM, Michael Jones <m.pricejones@gmail.com>wrote:

> Hi Patrick,
>
> Thank you for using Breathe.  I've very happy to hear it is (mostly)
> working well for you :)  Especially if it is a large project as I've not
> put much effort into seeing how the code scales on larger code bases.
>
> I honestly thought this functionality worked.  I'd have to look closer to
> see what has gone wrong.  Thank you for the thorough break down, if you're
> interested in contributing I'd be very happy for you to have a go but I'm
> afraid it has been sufficiently long since I worked with that part of the
> code that I've forgotten the details.  I've got a busy weekend ahead of me
> but I'd be happy to look next week.
>
> I think the class name is created by the *CompoundTypeSubRenderer* class
> in the *index.py* file in that *render/rst/doxygen* folder.  That does
> seem to be making an effort to create the target but it seems to be failing
> for some reason.  Some of the examples in the docs use the *no-link* option
> to stop the creation of the targets otherwise Sphinx gets confused if the
> same examples and targets are created in multiple parts of the same
> project, but I think the Nutshell example should work.
>
> Not sure why it isn't working, but please investigate if you are
> interested, otherwise I will next week.
>
> Thanks again for the report,
> Michael
>
>
>
> On Fri, Nov 16, 2012 at 5:47 AM, Patrick Cieplak <
> patrick.cieplak@gmail.com> wrote:
>
>> All,
>>
>> Thank you all very much for the Breathe project.   We have been using
>> Breathe with much success on a large C++ project.
>>
>> There does not seem to be a way to link to classes.  I'm not sure if this
>> feature is supported.  You can see this if you click on any of the links to
>> the Nutshell class on this page:
>>
>> http://michaeljones.github.com/breathe/#nutshellclass_nutshell
>>
>> Is this something that hasn't been implemented, or is it a bug?
>>
>> If you look at the MemberDefTypeSubRenderer class in the compound.py
>> file (
>> 
https://github.com/michaeljones/breathe/blob/master/breathe/renderer/rst/doxygen/compound.py),
>>  you can see that there are methods create_target and create domain_id.  It
>> seems that these methods are responsible for rendering the links and link
>> targets for various class members using the refid values from the Doxygen.
>>  The CompoundDefTypeSubRenderer class does not have these methods.  In
>> the doxygen xml, the class name comes in on the compounddef node, which in
>> turn contains the memberdef nodes, which contain information about the
>> class members.  Linking works great for the class members, just not the
>> classes themselves.
>>
>> If it is the case that class linking hasn't been implemented, what is the
>> most consistent way to implement this feature?  Would it be best to
>> implement the create_target and create_domain_id methods on the
>> CompoundDefTypeSubRenderer class?
>>
>> Thanks,
>> Patrick
>>
>
>