document companion guide more clearly

[ZenaMel]

I followed the Getting Started guide and it talks about what happens when I run Breathe but it never says how to call breathe to actually generate the docs.

This is where I would expect a "to run exhale, enter following command in your command-line:". Do I need to setup CMake in order to use breathe? Why is there no simple generate_docs.py example file inside the Getting Started guide?

Before changing my build configurations I'd at least like to see what I get with breathe on my codebase. Am I simply missing something?

[svenevs]

Hehe, such excellent questions! There's kind of a quagmire of tools involved or could be involved depending on your project. Is it open source / do you have a branch to look at? It's usually easier to explain options that way.

Otherwise what you're missing is that breathe and exhale are both sphinx extensions, and only run with make html (as would be possible after sphinx-quickstart) or by calling sphinx-build directly. Exhale will generate documents with breathe directives on them (.. doxygenfunction:: foo for example). You can test breathe without exhale by just putting a call to a directive on index.rst, but need to make sure you run doxygen somehow. Make sure you comment out exhale from the extensions list in conf.py!

Are you creating a docs target for CMake? That's not really documented but isn't very difficult :tm:

[ZenaMel]

Hey there @svenevs! I just got super confused because all I wanted was just a dump of what doxygen had already generated for me. What made everything click was the Companion you made (excellent work btw). It's super simple to see how all the moving pieces move together and I'm glad I found it. Would wish for it to be mentioned more directly in the Getting Started section.

Thanks for your quick reply! Problem solved and more than finally able to exhale.

[svenevs]

going to leave this open to remind me to document the companion guide better, and leave pinned in interim :slightly_smiling_face: