How generate dynamically the doc ?

[Ducatel]

Hi everybody,

I'm trying to move the documentation of my C++ projects to readthedoc. To do that, I'm trying to export my previous doxygen doc to the sphinx doc format (with breathe obviously :D )

But I'm new with sphinx/breathe and I don't really understand how I can "convert" my documentation.

So for me, my documentation should have:

• Alphabetical list of class
• A page for each class
• Alphabetical list of namespace
• A page for each namespace

I didn't found how I can do that. The only directive I found which generate automatically the doc is .. doxygenindex::. But it generate all doc in one page. That is very uncomfortable when you have hundreds of class.

The only way I found was to parse myself the doxygen XML output to generate rst file for each class/namespace. I think, it wasn't a good idea (not generic at all)

So There is any way to make what I want easily ? I miss somethings ?

Thanks in advance for your help ;)

[Andne]

I've been working on this for a work project myself. Eventually I found the breathe-apidoc command that generates an rst page for each class. Then you can have a manual page that uses something like

.. toctree::
   :glob:

   folder/class/*

to create the class lists.

Namespaces also have pages generated, though I have noticed that if you use anonymous namespaces much that list gets a little funny though, there was also a weird interaction with the file-level comments.

[svenevs]

Hey, I wrote exhale to do this. I've wanted to put a link to it on here for a long time, but it is currently not perfect. The warning at the top of the example page explains the current limitations, though I think I just fixed the template stuff. Templates are actually why I'm on the breathe issues page right now though...

I hope it is useful to you!

[ZedThree]

breathe-apidoc was exactly what I was looking for as well. From what I can tell, it's not mentioned in the documentation anywhere -- I only found out about it from @Andne's comment.

It would be good to have a short section about it in the documentation.

[evertheylen]

breathe-apidoc was what I was looking for, this should definitely be documented better. (That being said, the provided output could use some work)

[vermeeren]

For now assuming that apidoc and/or exhale resolves this issue. Documentation will be updated in #357.

[svenevs]

Hey @melvinvermeeren do you want to re-open and assign this to me? I put on my internal agenda to add a docs PR explaining how to use the breathe api-doc but forgot about that. I can put it on the docket for this weekend when I'm reinvestigating the templates stuff :)

Of course if weeks go by, assigned to me makes me accountable so ping me reminding me I promised to do this!

[vermeeren]

@svenevs thank you for the offer. It appears that only people with write access can be assigned to an issue. As Michael is the owner is this repo I cannot give you rights either. I will re-open this and bug you once in a while if I don't forget. :)

[vermeeren]

Hi @svenevs

[MaximilienNaveau]

Sorry to bother you guys bu in the latest documentation I couldn't find information about breath-apidoc. I found out about this tools in the exhale package... It is a great tool, which might need slight improvement but very efficient! If the documentation exists please point me toward it and make it more obviously available in the breath doc. Otherwize please write a little bit of doc about it for further users^^

[vermeeren]

@MaximilienNaveau breathe has a significant lack of contributors for things like this. If you could help out and write a little bit of documentation for breathe-apidoc and submit it as a PR that would be great.