From 63f59daa8d5cd1d1535968cf74854286532caf69 Mon Sep 17 00:00:00 2001 From: Jesse Vincent Date: Wed, 13 Mar 2024 13:02:56 -0700 Subject: [PATCH] * A first pass at trying to get doxygen and exhale and breathe to play nice so we can have api-level docs - Update Doxyfile config for better group and inline class display - Update INPUT path in Doxyfile for plugin documentation inclusion - Update copyright year in conf.py and adjust Sphinx settings - Add conditional compilation directives to skip specific sections in HIDTables.h and key_indexes.h files - Doc cRGB struct in None.h for RGB values representation --- docs/Doxyfile | 12 +++++++----- docs/conf.py | 10 ++++++---- plugins/KeyboardioHID/src/HIDTables.h | 4 ++++ src/kaleidoscope/HIDTables.h | 4 +++- src/kaleidoscope/device/key_indexes.h | 8 +++++++- src/kaleidoscope/driver/led/None.h | 12 ++++++++++++ 6 files changed, 39 insertions(+), 11 deletions(-) diff --git a/docs/Doxyfile b/docs/Doxyfile index 4e2b942c2e..2f23870e64 100644 --- a/docs/Doxyfile +++ b/docs/Doxyfile @@ -393,7 +393,7 @@ DISTRIBUTE_GROUP_DOC = NO # is disabled and one has to add nested compounds explicitly via \ingroup. # The default value is: NO. -GROUP_NESTED_COMPOUNDS = NO +GROUP_NESTED_COMPOUNDS = YES # Set the SUBGROUPING tag to YES to allow class member groups of the same type # (for instance a group of public functions) to be put as a subgroup of that @@ -413,7 +413,7 @@ SUBGROUPING = YES # SEPARATE_MEMBER_PAGES. # The default value is: NO. -INLINE_GROUPED_CLASSES = NO +INLINE_GROUPED_CLASSES = YES # When the INLINE_SIMPLE_STRUCTS tag is set to YES, structs, classes, and unions # with only public data fields or simple typedef fields will be shown inline in @@ -461,7 +461,7 @@ LOOKUP_CACHE_SIZE = 0 # normally produced when WARNINGS is set to YES. # The default value is: NO. -EXTRACT_ALL = NO +EXTRACT_ALL = YES # If the EXTRACT_PRIVATE tag is set to YES, all private members of a class will # be included in the documentation. @@ -823,7 +823,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = ../src +INPUT = ../src ../plugins/*/src ../plugins/*/README.md ../plugins/*/examples # This tag can be used to specify the character encoding of the source files # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses # libiconv (or the iconv built into libc) for the transcoding. See the libiconv @@ -2175,7 +2175,9 @@ INCLUDE_FILE_PATTERNS = # recursively expanded use the := operator instead of the = operator. # This tag requires that the tag ENABLE_PREPROCESSING is set to YES. -PREDEFINED = +# extra defs for to help with building the _right_ version of the docs +PREDEFINED = DOXYGEN_DOCUMENTATION_BUILD +PREDEFINED += DOXYGEN_SHOULD_SKIP_THIS # If the MACRO_EXPANSION and EXPAND_ONLY_PREDEF tags are set to YES then this # tag can be used to specify a list of macro names that should be expanded. The diff --git a/docs/conf.py b/docs/conf.py index 870204c9a4..316bedd41b 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -20,7 +20,7 @@ # -- Project information ----------------------------------------------------- project = 'Kaleidoscope' -copyright = '2023, Keyboardio & Friends' +copyright = '2024, Keyboardio & Friends' author = 'Keyboardio & Friends' @@ -30,8 +30,8 @@ # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom # ones. extensions = [ - #'breathe', - #'exhale', + 'breathe', + 'exhale', 'recommonmark', 'sphinx_markdown_tables' ] @@ -55,6 +55,8 @@ "doxygenStripFromPath": "..", # Suggested optional arguments "createTreeView": True, + "fullToctreeMaxDepth": 1, # Adjust depth based on your preference + # TIP: if using the sphinx-bootstrap-theme, you need # "treeViewIsBootstrap": True, "exhaleExecutesDoxygen": True, @@ -106,7 +108,7 @@ 'collapse_navigation': True, 'sticky_navigation': True, - 'navigation_depth': 8, + 'navigation_depth': 2, 'includehidden': False, 'titles_only': True } diff --git a/plugins/KeyboardioHID/src/HIDTables.h b/plugins/KeyboardioHID/src/HIDTables.h index 53f9110889..55a8330872 100644 --- a/plugins/KeyboardioHID/src/HIDTables.h +++ b/plugins/KeyboardioHID/src/HIDTables.h @@ -24,6 +24,8 @@ THE SOFTWARE. #pragma once +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) + // These mappings were extracted and transcribed from // https://www.usb.org/sites/default/files/hut1_2.pdf @@ -795,3 +797,5 @@ THE SOFTWARE. // Reserved 0x2D5-4FF // HID_CONTACT_* (not included here) 0x500-514 // Reserved 0x515-FFFF +// +#endif DOXYGEN_SHOULD_SKIP_THIS diff --git a/src/kaleidoscope/HIDTables.h b/src/kaleidoscope/HIDTables.h index 7e309df504..08e506838c 100644 --- a/src/kaleidoscope/HIDTables.h +++ b/src/kaleidoscope/HIDTables.h @@ -17,7 +17,7 @@ #pragma once // clang-format off - +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) // These mappings were extracted and transcribed from // https://www.usb.org/sites/default/files/hut1_2.pdf // @@ -786,3 +786,5 @@ // Reserved 0x2D5-4FF // HID_CONTACT_* (not included here) 0x500-514 // Reserved 0x515-FFFF +// +#endif diff --git a/src/kaleidoscope/device/key_indexes.h b/src/kaleidoscope/device/key_indexes.h index 98365e87aa..72c5a352f9 100644 --- a/src/kaleidoscope/device/key_indexes.h +++ b/src/kaleidoscope/device/key_indexes.h @@ -16,7 +16,9 @@ */ #pragma once - +#if !defined(DOXYGEN_SHOULD_SKIP_THIS) +// doxyskip +#if defined(DOXYGEN_SHOULD_SKIP_THIS) #include // for uint8_t #include "kaleidoscope/KeyAddr.h" // for KeyAddr @@ -34,6 +36,8 @@ constexpr uint8_t keyIndex(uint8_t row, uint8_t col) { constexpr uint8_t R0C0 = keyIndex(0, 0); constexpr uint8_t R0C1 = keyIndex(0, 1); + + constexpr uint8_t R0C2 = keyIndex(0, 2); constexpr uint8_t R0C3 = keyIndex(0, 3); constexpr uint8_t R0C4 = keyIndex(0, 4); @@ -932,3 +936,5 @@ constexpr uint8_t R29C26 = keyIndex(29, 26); constexpr uint8_t R29C27 = keyIndex(29, 27); constexpr uint8_t R29C28 = keyIndex(29, 28); constexpr uint8_t R29C29 = keyIndex(29, 29); +#endif +#endif // DOXYGEN_SHOULD_SKIP_THIS diff --git a/src/kaleidoscope/driver/led/None.h b/src/kaleidoscope/driver/led/None.h index 57d601e05c..a9fcdb90e1 100644 --- a/src/kaleidoscope/driver/led/None.h +++ b/src/kaleidoscope/driver/led/None.h @@ -15,12 +15,24 @@ * this program. If not, see . */ + + + + #pragma once +/** \file */ #include // for uint8_t #ifndef CRGB +/** + * \struct cRGB None.h kaleidoscope/driver/led/None.h + * + * \brief A struct representing an RGB value. + */ + + struct cRGB { uint8_t r, g, b; };