Two pass doctree transforms

[shimizukawa]

Hi,

I'm the maintainer of the Breathe extension for Sphinx. Breathe provides a way to get doxygen information into the Sphinx output. It works with the doxygen xml and normally expects the xml files to have been generated prior to the Sphinx build.

However, now we're attempting to implement a system in which Breathe manages the doxygen xml generation. To do this we'd like to figure out all the C++ source files referenced by Breathe directives which therefore need to have doxygen xml generated from them and then automatically run doxygen on them and then process the resulting xml into the Sphinx output.

It seem to me that I need to be able to scan over all the rst source files once to collect the information and then go over them again to be able to process them properly with all the information at hand. My initial approach used the docutils Transforms but they seem to be applied to each file in isolation rather than across the whole project.

Can you recommend an approach I might take for this? I'm struggling to see my best way forward with the current events and API. I thought maybe a "all-sources-read" type event which would allow me to load up doctrees and edit them before the final reference resolving was complete. I welcome suggestions though.

Thanks,
Michael

---

• Bitbucket: https://bitbucket.org/birkenfeld/sphinx/issue/1440
• Originally reported by: michaeljones
• Originally created at: 2014-04-07T12:09:34.719

[shimizukawa]

From michaeljones on 2014-04-20 12:38:51+00:00

I have taken a closer look at the Sphinx code and I cannot see an easy or obvious way of including this which wouldn't either require a large change or place significant burden on the extension writer to correctly read/write doctrees, etc.

I think it is an interest issue to ponder and in an ideal world it would be overcome but I will pursue a different direction and I would be happy for this to be closed out as "Won't fix".

Michael

[shimizukawa]

From Takayuki Shimizukawa on 2014-07-29 04:54:01+00:00

Thanks for reporting. Now close as won't fix.

Note: this topic is discussed at: https://groups.google.com/d/msg/sphinx-dev/6GaqL89BsKU/IWBxgZpfm78J