Linking to dot graphs

[hobu]

It would be really handy to have an option to the renderer that would link back to graphviz output from the HTML renderer of Doxygen. What I was thinking is an app-level option that takes in the path to the html output of Doxygen, and then an :image: option or some such available to classes (and the index directive too, I suppose), templated classes, etc that simply does an img link back to that location.

The app-level option the user gives would simply be the precursor part of the URL that is generated for the img tag. Make sense?

If I want to implement this, what steps should I take? I fumbled around for #44, and I never really figured out how to bolt options in to do it. Any pointers you can provide to help me bootstrap this would be appreciated. I'll take on the task once you help me get the ball rolling.

[michaeljones]

Wow, love your attitude :) Thanks for being so proactive.

It would be ace to support those graphviz diagrams. I'll give it a little bit of thought and try to get back to you with a possible route to a solution. Hopefully I'll get you something by this time tomorrow, but if not it might have to wait for next week.

Thanks again,
Michael

[michaeljones]

Hey,

Sorry, I've failed to take the time for this and am now away for the weekend.

Very broadly, I think you're on the right track, I'd just try to use the filters framework combined with an option on the doxygenclass directive to figure out if it needs to be rendered. You'll have to expose the html path in the conf.py as you said, maybe allow the breathe_projects to have entries for both xml and html on a per project basis.

The filters framework is a little crazy but is the best thing we have right now for putting in this kind of logic in a modular way. Could be complicated by where you think the diagram should best be placed in the final output. It might also be desirable to have it as a separate directive so that people can choose (though then it can't be embedded within the class output just before or after.)

Anyway, happy to try to provide more info early next week. Sorry for the delay, thanks again,
Michael

[hobu]

I probably won't be able to get to this for a week or two either. I looked around, and it would seem useful to have an options object that is passed around instead of adding new function parameters as is done now. Otherwise, adding a new option seems to require touching a lot of code to get it pushed down far enough to be useful. Do you agree with this assessment?

[michaeljones]

Hey,

So it really isn't much but I've pushed a "doxygendiagram" branch which contains some basic code to get this moving. I've got it as a separate directive for the moment but I can definitely see the need to get it integrated with the class directive. Just need to figure out the appropriate way of displaying it.

Currently it just shows the image. I think it would be good to go and parse the html and get the area-link information so that we can markup the image with appropriate class links. Of course, that would only be valid for html output so it'll take some work to make sure it happens in a nice compatible way that behaves well with pdf output and the like.

I'll spend some more time on it soon, I'm sorry I've been so slack,
Michael

[guyguy333]

Hi @michaeljones

Any news for this feature ?
Do you plan to merge doxygendiagram branch to master ?

Thank you

[MilesCranmer]

^I'm also very interested in this

[vermeeren]

I have not checked the doxygendiagram branch, but if it is adapted to current Breathe version and implements a "minimal" or "suboptimal" solution then I would still propose merging.

Having basic functionality for this would be better than having none at all in my opinion.

[SteffenSeckler]

Even though this is very old, is there any news on this?
Inheritance diagrams would really help understand our code a lot :)

[samuel-emrys]

Also very interested in this, @michaeljones do you have any plans to further develop the solution on the doxygendiagram branch? If so, have you had any additional thoughts with respect to how you'd like this feature implemented? I might be able to provide some dev effort if you can provide some details about your vision for implementation. I agree with @vermeeren , a minimal or suboptimal implementation provides vastly more value than no implementation at all.

[orlandini]

I am loving breathe so far, and this feature would be great. Just showing my support (:

[2bndy5]

Using doxygen v1.8.17 (on Linux) and v1.9.1 (on windows), I noticed that the XML contained the Dot source code in a <para><dot>...</dot></para> tag. Since sphinx can be made to use the dot executable (using the .. graphviz:: directive), wouldn't it be possible to feed the dot source to sphinx like we would normally from rst?

I don't know the mechanics of breathe that well. My first impression of going about using a graph as an image seems over-complicated to me. Why not offload the work to sphinx?

[jakobandersen]

Using doxygen v1.8.17 (on Linux) and v1.9.1 (on windows), I noticed that the XML contained the Dot source code in a <para><dot>...</dot></para> tag. Since sphinx can be made to use the dot executable (using the .. graphviz:: directive), wouldn't it be possible to feed the dot source to sphinx like we would normally from rst?

That sounds like a good idea to me.

I don't know the mechanics of breathe that well. My first impression of going about using a graph as an image seems over-complicated to me. Why not offload the work to sphinx?

Yes, generally the idea is to translate into Sphinx constructs as directly as possible, and only make workarounds when strictly needed.

It would be great if you could provide a small test project to start making a solution from.

[2bndy5]

It would be great if you could provide a small test project to start making a solution from.

That's the least I can do! Here you go:
dot_breathe.zip
EDITED: added captions and a @dotfile cmd to demonstrate what "extra" data could be passed to .. graphviz:: directive.

dotfile XML output

<dotfile name="C:/full/path/to/project/dot_breathe/example.dot">Caption</dotfile>

dot XML output

<dot caption="Caption">
// dot source code here
</dot>

I didn't use any hyperlinked nodes in the graphs (it was copied from Graphviz gallery/example). My only concern is when the dot source uses special doxygen cmds like @ref in nodes' URL, but maybe that could be sorted when filtering out XML special char (like ").

[2bndy5]

I've been trying to figure this lib out (all day), but I can't seem to wrap my head around how the filters work. I'm creating a docDotFileType object when \dotfile is found within a para tag, but it seems to get filtered out somehow. I created a visit_docdotfile() function to return a graphviz directive object, but it never gets called (despite "docdotfile": visit_docdotfile in the SphinxRenderer.methods dict).

I think something might need to be added to visit_docpara(), but I'm pretty much poking around in the dark at this point. 🙈

ps - the docDotFileType seems to have been generated almost 12 years ago but never actually used. Once I get this working, passing a \dot cmd to graphviz directive should be almost identical.

[2bndy5]

Success!

Regarding my last post about confusion: I had no idea that the doc*TypeSub classes were actually doing the parsing from XML. Once the docParaTypeSub.buildChildren() was adjusted, progress was made swiftly.

I now have both \dot & \dotfile cmds being translated into graphviz nodes. I also had to replicate some of the code from Graphviz.run() in sphinx/ext/graphviz.py as the sphinx directive expects a relative path to the dot file when doxygen xml uses the absolute path instead. Furthermore, I have the captions also being output (when specified) using an rst figure node (exactly like Graphviz.run() does).

Instead of posting code changes, I'll submit a PR (after cleaning up my debug print() calls). I'll also be noting some inherent limitations in the upcoming PR...

[2bndy5]

hit a snag when \ref cmd is embedded in the dot synatx for cross referencing... Now I have to figure out how this lib handles the @ref cmd. My first guess is visit_ref().
Sample XML:

<para><dot caption="graph in struct scope">
digraph {
    b [ label=&quot;class Dummy&quot; URL=&quot;\ref Dummy&quot;];
    c [ label=&quot;struct Test&quot; URL=&quot;@ref Test&quot;];
    b -&gt; c;
}
</dot>

Currently, I'm afraid to alter any dot syntax, but I'll have to experiment more.

[2bndy5]

Given the sample output above and the graphviz directive's inability to handle roles embedded in the dot syntax, I'm concluding that we cannot support references using doxygen's @ref cmd inside the dot syntax.

I suppose it could be addressed, but we would need doxygen to output a

<ref refid="..." kindref="...">...</ref>

for any occurrences found within the dot syntax (instead of literally text like @ref ...).

[jakobandersen]

Your progress sounds really good! Please do make a PR when possible to make it easier to discuss details and test it out.

Regarding the @ref inside Graphviz data I have the same feeling that this may be very difficult to convert correctly, but let's see.

[2bndy5]

I think I need to add to breathe's "Supported Features" docs to highlight the limitations of this approach. After that, I'll submit a PR.

[2bndy5]

I think I mis-perceived this issue.

My approach only aims to address \dot & \dotfile cmds which are not the same as the graphs configured by Doxyfile tags. In my research, I found that no XML output is produced for the call/caller graphs that can be generated by doxygen. However, the include/inheritance graphs generated by doxygen (if enabled & relevant) have some output in the header file's (& data structure's) XML output.

sample of include graph from header XML

    <incdepgraph>
      <node id="1">
        <label>ReceiverCode/src/utilities/common.h</label>
        <link refid="common_8h"/>
        <childnode refid="2" relation="include"></childnode>
        <childnode refid="3" relation="include"></childnode>
      </node>
      <node id="3">
        <label>EEPROM.h</label>
      </node>
      <node id="2">
        <label>stdint.h</label>
      </node>
    </incdepgraph>
    <invincdepgraph>
      <node id="3">
        <label>ReceiverCode/src/main.cpp</label>
        <link refid="_receiver_code_2src_2main_8cpp"/>
      </node>
      <node id="1">
        <label>ReceiverCode/src/utilities/common.h</label>
        <link refid="common_8h"/>
        <childnode refid="2" relation="include"></childnode>
      </node>
      <node id="2">
        <label>ReceiverCode/src/utilities/radio.h</label>
        <link refid="radio_8h"/>
        <childnode refid="3" relation="include"></childnode>
      </node>
    </invincdepgraph>

which results in:

It would take some doing to translate this XML tree to dot syntax (for invocation of sphinx graphviz directive).

[2bndy5]

Done! #757 now supports doxygen generated graphs as well as the doxygen \dot & \dotfile cmds.