* 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

@@ -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

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
 }

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

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

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 <stdint.h>  // 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

src/kaleidoscope/driver/led/None.h

@@ -15,12 +15,24 @@
  * this program. If not, see <http://www.gnu.org/licenses/>.
  */
 
+
+
+
+
 #pragma once
+/** \file */
 
 #include <stdint.h>  // 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;
 };