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. -- You received this message because you are subscribed to the Google Groups "sphinx-users" group. To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users+unsubscr...@googlegroups.com. To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/55990af6-777f-4842-9b96-bcccef817fe1n%40googlegroups.com.
