Running into some issues using Sphinx with C++

[Jesse Vincent]

Hi folks, 

I'm one of the people behind Kaleidoscope, an open source firmware for computer keyboards built on top of Arduino.  Kaleidoscope is implemented in C++ and makes use of templates and macros to help provide a somewhat more friendly API to end-users who are customizing their keyboards.

As we've been trying publish docs to readthedocs (https://kaleidoscope.readthedocs.io/), I've been attempting to use Sphinx and Exhale to publish API documentation. 

I've been struggling to make things go and figured I ought to reach out here before opening a bunch of possibly incoherent bug reports on GitHub.

Jakob Andersen very kindly fixed the first parsing issue I ran into instantly (https://github.com/sphinx-doc/sphinx/issues/7853)

Running 3.x HEAD, that issue is indeed resolved,  but I quickly run into others. 

If you're interested in replicating what I'm seeing (and are running 3.x HEAD):

$ git clone -b sphinx-issues https://github.com/keyboardio/Kaleidoscope

$ cd Kaleidoscope/docs

$ make html

If anyone has any words of wisdom, I'm running out of rational ideas and am starting to think horrible thoughts about using Doxygen's raw output.

I -think- I'd be happyish if Sphinx was able to log constructs it couldn't parse and otherwise ignore them. If I could do that, then at least we could generate docs for end users, even if they weren't 100% complete.  I think I'd even be cool annotating code with comments to give Sphinx hints about what to do for constructs it can't cope with.

Thanks so much!

Jesse

An example where template parsing throws Sphinx for a loop:

sphinx.util.cfamily.DefinitionError: Error when parsing function declaration.

If the function has no return type:

  Error in declarator or parameters-and-qualifiers

  Invalid C++ declaration: Expecting "(" in parameters-and-qualifiers. [error at 54]

    template<>  __attribute__ ((weak)) EventHandlerResult Hooks

    ------------------------------------------------------^

If the function has a return type:

  Error in declarator or parameters-and-qualifiers

  If pointer to member declarator:

    Invalid C++ declaration: Expected '::' in pointer to member (function). [error at 59]

      template<>  __attribute__ ((weak)) EventHandlerResult Hooks

      -----------------------------------------------------------^

  If declarator-id:

    Invalid C++ declaration: Expecting "(" in parameters-and-qualifiers. [error at 59]

      template<>  __attribute__ ((weak)) EventHandlerResult Hooks

      -----------------------------------------------------------^

Another example where macros are at fault:

  File "/usr/local/lib/python3.7/site-packages/Sphinx-3.2.0.dev20200620-py3.7.egg/sphinx/domains/cpp.py", line 6100, in _parse_type

    raise self._make_multi_error(prevErrors, header)

sphinx.util.cfamily.DefinitionError: Error when parsing function declaration.

If the function has no return type:

  Error in declarator or parameters-and-qualifiers

  Invalid C++ declaration: Expected identifier in nested name. [error at 9]

    KEYMAPS ([0]=KEYMAP_STACKED(Key_NoKey, Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey, Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab, Key_PageUp, Key_A, Key_S, Key_D, Key_F, Key_G, Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape, Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift, Key_NoKey, Key_skip, Key_6, Key_7, Key_8, Key_9, Key_0, Key_skip, Key_Enter, Key_Y, Key_U, Key_I, Key_O, Key_P, Key_Equals, Key_H, Key_J, Key_K, Key_L, Key_Semicolon, Key_Quote, Key_skip, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus, Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl, Key_NoKey),) void setup()

    ---------^

If the function has a return type:

  Error in declarator

  If declarator-id with parameters-and-qualifiers:

    Invalid C++ declaration: Expected identifier in nested name. [error at 8]

      KEYMAPS ([0]=KEYMAP_STACKED(Key_NoKey, Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey, Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab, Key_PageUp, Key_A, Key_S, Key_D, Key_F, Key_G, Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape, Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift, Key_NoKey, Key_skip, Key_6, Key_7, Key_8, Key_9, Key_0, Key_skip, Key_Enter, Key_Y, Key_U, Key_I, Key_O, Key_P, Key_Equals, Key_H, Key_J, Key_K, Key_L, Key_Semicolon, Key_Quote, Key_skip, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus, Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl, Key_NoKey),) void setup()

      --------^

  If parenthesis in noptr-declarator:

    Error in declarator or parameters-and-qualifiers

    If pointer to member declarator:

      Invalid C++ declaration: Expected identifier in nested name. [error at 9]

        KEYMAPS ([0]=KEYMAP_STACKED(Key_NoKey, Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey, Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab, Key_PageUp, Key_A, Key_S, Key_D, Key_F, Key_G, Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape, Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift, Key_NoKey, Key_skip, Key_6, Key_7, Key_8, Key_9, Key_0, Key_skip, Key_Enter, Key_Y, Key_U, Key_I, Key_O, Key_P, Key_Equals, Key_H, Key_J, Key_K, Key_L, Key_Semicolon, Key_Quote, Key_skip, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus, Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl, Key_NoKey),) void setup()

        ---------^

    If declarator-id:

      Invalid C++ declaration: Expected identifier in nested name. [error at 9]

        KEYMAPS ([0]=KEYMAP_STACKED(Key_NoKey, Key_1, Key_2, Key_3, Key_4, Key_5, Key_NoKey, Key_Backtick, Key_Q, Key_W, Key_E, Key_R, Key_T, Key_Tab, Key_PageUp, Key_A, Key_S, Key_D, Key_F, Key_G, Key_PageDown, Key_Z, Key_X, Key_C, Key_V, Key_B, Key_Escape, Key_LeftControl, Key_Backspace, Key_LeftGui, Key_LeftShift, Key_NoKey, Key_skip, Key_6, Key_7, Key_8, Key_9, Key_0, Key_skip, Key_Enter, Key_Y, Key_U, Key_I, Key_O, Key_P, Key_Equals, Key_H, Key_J, Key_K, Key_L, Key_Semicolon, Key_Quote, Key_skip, Key_N, Key_M, Key_Comma, Key_Period, Key_Slash, Key_Minus, Key_RightShift, Key_RightAlt, Key_Spacebar, Key_RightControl, Key_NoKey),) void setup()

        ---------^

The full traceback has been saved in /var/folders/hv/wfz5y4fs3hbbzb0bjmnl07rw0000gn/T/sphinx-err-z6lf0cbw.log, if you want to report the issue to the developers.