support \example commmand? (Verbose output: KeyError on example)

[svenevs]

/// @example auto render_pass_ci = make_info<VkRenderPassCreateInfo>();

Results into

(!) Exhale: could not generate reStructuredText documents :/Traceback (most recent call last):
  File "c:\python39\lib\site-packages\exhale\__init__.py", line 25, in environment_ready
    deploy.explode()
  File "c:\python39\lib\site-packages\exhale\deploy.py", line 423, in explode
    textRoot.toConsole()
  File "c:\python39\lib\site-packages\exhale\graph.py", line 3823, in toConsole
    self.consoleFormat(
  File "c:\python39\lib\site-packages\exhale\graph.py", line 3880, in consoleFormat
    l.toConsole(0, fmt_spec)
  File "c:\python39\lib\site-packages\exhale\graph.py", line 543, in toConsole
    c.toConsole(level + 1, fmt_spec)
  File "c:\python39\lib\site-packages\exhale\graph.py", line 516, in toConsole
    kind=utils._use_color(self.kind, fmt_spec[self.kind], sys.stderr),
KeyError: 'example'

Not 100% sure if thats the same issue.
Ignore that its a wrong doxygen usage too

Originally posted by @IceflowRE in #39 (comment)

Hey @IceflowRE thanks for reporting, this one is indeed slightly different. The doxygen example command seems to be setup in a way where you can cross-reference code examples in other files and such. I don't anticipate being able to resolve this directly anytime soon though 😢

I actually designed it to crash like this in the same spot for pretty much anything I didn't explicitly support. For \example specifically, the workaround I suggest is to stop using the doxygen \example command and instead use sphinx alternatives. You should still be able to write documentation in header files to link to things, but you would instead need to manually structure your examples rather than have exhale do it. Long term it would be sweet if I could get sphinx.ext.viewcode working but that's an even bigger cookie.

Example:

1. In some function or class docs or whatever in your headers

   /**
    * \brief some thing that does stuff
    *
    * \rst
    * See the :ref:`some_special_example` for more information.
    * \endrst
    */
   

   The trick being to enter a raw rst block (also wish I could do that inline but never figured it out...), and now you can use an rst role to link to some other document you are creating.

2. Create the target to be linked to manually. It can just be a mostly blank wrapper file, e.g., docs/examples/some_special_example.rst, with a heading (or something else) you can link to. Those rules come from docutils (sphinx sits on top of that), the below example is an internal crossreference target which is why in (1) we had the :ref: role being used. And then for the code, to keep things mostly automated, you can just use literalinclude or one of the other code options

   .. _some_special_example:
   Some Special Example
   ====================
   
   Any special description you want about it that's not in the file.
   
   .. literalinclude:: ../../src/examples/some_special_example.cpp

To be clear, the above workaround is not a replacement of \example, just hoping to get you in a place where you have the examples documented that you want. Hopefully the above works, happy to try and answer more questions but am generally in open source shutdown.

[svenevs]

I guess to clarify, if you just want things to work then fork the project or create a PR like #84 I just won't merge it. Interface support requires more than just that, and so would this, but in terms of running things it'll just get skipped. Sorry for all the confusion, lots of moving parts both in this project and the associated tools 🙂

[IceflowRE]

For \example specifically, the workaround I suggest is to stop using the doxygen \example command and instead use sphinx alternatives.

Makes actually much sense ^^

Also would it be possible to put a message like unsupported doxygen command? Would clearify a lot.

lots of moving parts both in this project and the associated tools

Iam happy for every day this tool works ^^