sphinx-autogen equivalent about breathe HOT 9 CLOSED

I have been following the development of breathe with great interest, and this feature would allow me to finally adopt breathe into my project and generate C++ API documentation with Sphinx. In particular, I would like to implement support for Doxygen grouping.

Could you provide me with hints on the reST generation within breathe, e.g. how to generate separate output files?

from breathe.

Hi Peter,

Thanks for showing interest. Just to clarify, there isn't any support for this at the moment. I would imagine that it wouldn't be too hard to achieve as it would mostly involve parsing the xml, iterating over the resulting tree and generating appropriately named files at whatever depth you were interested in.

I would think that the reST file could be generated with simple file write calls rather than any specific reST generation mechanism, though maybe I'm missing something here.

It is worth noting that I'm not worked with Doxygen grouping before so I'm not sure exactly how it is handled in the xml.

Are you familiar with the code at all? breathe.parser.doxygen.index and breathe.parser.doxygen.compound have functions in them for parsing an xml file to create the appropriate tree. breathe.renderer.rst.doxygen.index has an example of going from the compound object in the index xml file to the corresponding compound xml file.

Not sure if any of that makes sense. Happy to try to help if you let me know where you're at. Otherwise I could probably take a look at this this weekend, if you provide a clear enough idea of the results you'd like. ie. one class per file or one group per file, or something.

Cheers,
Michael

from breathe.

Hi Michael,

yes, I did look into the code a bit, and I grasped the core concept of parsing doxygen XML into a tree of node objects, and applying a filter based on the given doxygen* directive. Further I glanced at sphinx.ext.autosummary, and the apidoc script in Sphinx 1.1.

I think I initially misunderstood the intent of this feature: My thought was to generate separate reST files with appropriate doxygen* directives within the breathe extension, not with a separate script. Would this be possible? Implement one or more filters, which, when applied to the parsed tree, generate separate output files using the reST renderer of breathe? For example, one file per C++ namespace with all contained classes?

Alternatively, maybe a doxygennamespace or doxygenmodule directive is easier to implement? In my project [whose name I will reveal once it has proper API documentation ;-)] the number of namespaces remains pretty much the same, so manually creating ReST source files with one doxygennamespace directive each does not seem to much of a burden.

Peter

from breathe.

Maybe the granularity provided by doxygenclass is preferable after all. I implemented a doxygennamespace directive as a minimal variation of the doxygenfile directive, and while it works, the result is not quite what I had in mind: it would be nice to have "namespace testnamespace" as a section heading, and omit the extra indentation level for the classes. Then I realized that what I really desire is some form of customization, e.g. through templates, which is beyond the scope of breathe. So I will content myself with manual doxygenclass directives, which allows omission of unneeded helper classes and template spezializations.

Anyway, thank you, Michael, for writing a very useful Sphinx extension :-).

from breathe.

Hi Peter,

You're right that my original intention was for a script that could be run to generate the reST files, with appropriate titles and doxygen* directives, in the sphinx source directory along side your hand written files. I wasn't sure that there was another option, however I haven't looked at the Sphinx autosummary docs in a while and it seems they also support the autosummary_generate config value as well.

I'm not sure of the best approach as even the sphinx-autogen script doesn't work quite as I had expected. It scans for the autosummary directive in your docs and creates files to match rather than scanning your code and creating files to match the modules and classes.

I'll try to give it some thought. I'd welcome any opinions you have as I think breathe could benefit from any kind of functionality in this direction.

And, yes, the extra indentation in the doxygenfile implementation is currently unappealing. I'd like to change it but I'm also in the mind to gut the finder stuff remove all the matcher classes and replace them with the filter functionality from the rendering side if possible as I find the latter cleaner. That is a big step though so I've not managed to find the time for it.

Anyway, thank you for your time, your comments and the efforts you have made to investigate this issue and try Breathe in the first place. I'm glad you're finding it useful.

Michael

from breathe.

Oh, now I see that there is a similar request to mine #99. Indeed, this feature would make Breathe finally applicable for an API documentation. Generating those documents is a step before Sphinx processes the docs. So I think this should not be done in a a directive, but rather a global config option and a script as Michael suggested. A hook to builder-inited could do the trick.

I had a look at the source code to see if I could contribute a little bit. But I'm still learning Python and since I lack of a good code browser, navigating through all the scattered mini-classes and factories feels rather painful.

from breathe.

Checkout #241 for a beta implementation.

from breathe.

@michaeljones Perhaps this issue can be closed now since the new breathe-apidoc script is exactly

Something that will generated the appropriate rst stub files with breathe directives for different classes/files/functions/etc.

or is it missing some functionality that you had in mind?

from breathe.

I do indeed believe that breathe-apidoc is what OP describes. Closing for now, comment if you disagree.

from breathe.