fix: Doc build issues in CI preventing API reference from showing properly on web (#534)

* fix: Doc build issues in CI preventing API reference from showing properly on web

* fix title underline

* cleaning up docs some

* clean up build system some

* fix docs

* fix sp

* cleanup

Author: finger563

.github/workflows/build_and_publish_docs.yml

@@ -13,15 +13,16 @@ jobs:
       contents: write
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v5
         with:
-          fetch-depth: 0
+          fetch-depth: 1
           fetch-tags: true
 
       - name: Set up Python
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
-          python-version: "3.11"
+          python-version: "3.13"
+          cache: 'pip'
 
       - name: Install Dependencies
         run: |
@@ -33,7 +34,7 @@ jobs:
         run: |
           cd doc
           # ignore if the following command fails
-          build-docs -t esp32 -l en --project-path ../ --source-dir ./ --doxyfile_dir ./ || true
+          build-docs -bs html -t esp32 -l en --project-path ../ --source-dir ./ --doxyfile_dir ./ || true
           mkdir -p ../docs
           cp -r _build/en/esp32/html/* ../docs/.
           # go to the latex output

components/csv/include/csv.hpp

@@ -1,6 +1,8 @@
 #pragma once
 
+#ifndef __gnu_linux__
 #define __gnu_linux__
+#endif
 
 #include "csv2/reader.hpp"
 #include "csv2/writer.hpp"

components/drv2605/include/drv2605_menu.hpp

@@ -26,7 +26,7 @@ class Drv2605Menu {
   using Driver = espp::Drv2605;
 
   /// @brief Construct a new Drv2605Menu object.
-  /// @param i2c A vector of shared pointers to the Drv2605s to interact with.
+  /// @param drivers A vector of shared pointers to DRV2605 drivers to control.
   explicit Drv2605Menu(const std::vector<std::shared_ptr<Driver>> &drivers)
       : drivers_(drivers) {}
 

components/ftp/include/ftp_client_session.hpp

@@ -165,12 +165,8 @@ class FtpClientSession : public BaseComponent {
   }
 
   /// \brief Receive data from the client.
-  /// \details This function receives data from the client and stores it in
-  ///     the given buffer. This function uses the data socket and not the
-  ///     control socket, and handles both active and passive mode.
-  /// \param buffer The buffer to store the data in.
-  /// \param size The size of the buffer.
-  /// \return The number of bytes received.
+  /// \return The data received from the client, or std::nullopt if
+  ///         receiving the data failed.
   std::optional<std::vector<uint8_t>> receive_data() {
     if (is_passive_data_connection_) {
       if (!passive_socket_.is_valid()) {
@@ -653,7 +649,7 @@ class FtpClientSession : public BaseComponent {
   ///     take a second parameter. The first parameter is denoted by a single
   ///     Telnet character, as is the second Format parameter for ASCII and
   ///     EBCDIC; the second parameter for local byte is a decimal integer to
-  ///     indicate Bytesize. The parameters are separated by a <SP> (Space,
+  ///     indicate Bytesize. The parameters are separated by a \<SP\> (Space,
   ///     ASCII code 32).
   /// \param arguments The arguments to the TYPE command.
   /// \return True if the command was handled, false otherwise.

components/gt911/include/gt911.hpp

@@ -133,6 +133,8 @@ class Gt911 : public BasePeripheral<std::uint16_t> {
     POINT_5 = 0x816F,
   };
 
+#pragma pack(push, 1)
+
   // From Goodix library
   struct GTInfo {
     // 0x8140-0x814A
@@ -141,7 +143,7 @@ class Gt911 : public BasePeripheral<std::uint16_t> {
     uint16_t xResolution;
     uint16_t yResolution;
     uint8_t vendorId;
-  } __attribute__((packed));
+  };
 
   struct GTPoint {
     // 0x814F-0x8156, ... 0x8176 (5 points)
@@ -150,25 +152,25 @@ class Gt911 : public BasePeripheral<std::uint16_t> {
     uint16_t y;
     uint16_t area;
     uint8_t reserved;
-  } __attribute__((packed));
+  };
 
   struct GTLevelConfig {
     uint8_t touch; // Threshold of touch grow out of nothing
     uint8_t leave; // Threshold of touch decrease to nothing
-  } __attribute__((packed));
+  };
 
   struct GTStylusConfig {
     uint8_t txGain;
     uint8_t rxGain;
     uint8_t dumpShift;
     GTLevelConfig level;
     uint8_t control; // Pen mode escape time out period (Unit: Sec)
-  } __attribute__((packed));
+  };
 
   struct GTFreqHoppingConfig {
     uint16_t hoppingBitFreq;
     uint8_t hoppingFactor;
-  } __attribute__((packed));
+  };
 
   struct GTKeyConfig {
     // Key position: 0-255 valid
@@ -182,7 +184,7 @@ class Gt911 : public BasePeripheral<std::uint16_t> {
     uint8_t sens12;
     uint8_t sens34;
     uint8_t restrain;
-  } __attribute__((packed));
+  };
 
   struct GTConfig {
     // start at 0x8047
@@ -250,7 +252,9 @@ class Gt911 : public BasePeripheral<std::uint16_t> {
     // 0x8091
     uint8_t NC_5[2];
     GTKeyConfig keys;
-  } __attribute__((packed));
+  };
+
+#pragma pack(pop)
 
   std::atomic<bool> home_button_pressed_{false};
   std::atomic<uint8_t> num_touch_points_;

components/hid-rp/include/gamepad_imu.hpp

@@ -4,17 +4,20 @@
 
 namespace espp {
 namespace gamepad {
+
+#pragma pack(push, 1)
+
 /// Accelerometer data
 struct Accelerometer {
   union {
     struct {
       std::int16_t X;
       std::int16_t Y;
       std::int16_t Z;
-    } __attribute__((packed));
+    };
     std::int16_t raw[3];
-  } __attribute__((packed));
-} __attribute__((packed));
+  };
+};
 
 /// Gyroscope data
 struct Gyroscope {
@@ -23,14 +26,17 @@ struct Gyroscope {
       std::int16_t X;
       std::int16_t Y;
       std::int16_t Z;
-    } __attribute__((packed));
+    };
     struct {
       std::int16_t Pitch;
       std::int16_t Yaw;
       std::int16_t Roll;
-    } __attribute__((packed));
+    };
     std::int16_t raw[3];
-  } __attribute__((packed));
-} __attribute__((packed));
+  };
+};
+
+#pragma pack(pop)
+
 } // namespace gamepad
 } // namespace espp

components/hid-rp/include/hid-rp-gamepad.hpp

@@ -124,7 +124,7 @@ class GamepadInputReport : public hid::report::base<hid::report::type::INPUT, RE
   }
 
   /// Get the brake trigger value
-  /// @return brake trigger value
+  /// @param value brake trigger value
   constexpr void get_brake(TRIGGER_TYPE &value) const { value = trigger_axes[0]; }
 
   /// Get the left trigger value
@@ -146,7 +146,7 @@ class GamepadInputReport : public hid::report::base<hid::report::type::INPUT, RE
   }
 
   /// Get the accelerator trigger value
-  /// @return accelerator trigger value
+  /// @param value accelerator trigger value
   constexpr void get_accelerator(TRIGGER_TYPE &value) const { value = trigger_axes[1]; }
 
   /// Get the right trigger value

components/hid-rp/include/hid-rp-playstation.hpp

@@ -181,7 +181,7 @@ enum class PlaystationHat {
 /// - Android seems to require Audio support, which it cannot find over BLE, so
 ///   it does not work at all.
 ///
-/// \section hid_rp_playstation_ex1 HID-RP Playstation Gamepad Example
+/// \section hid_rp_playstation_ex2 HID-RP Playstation Gamepad Example
 /// \snippet hid_rp_example.cpp hid rp example
 template <uint8_t REPORT_ID = 1>
 class PlaystationDualsenseBLESimpleInputReport

components/hid-rp/include/hid-rp-switch-pro.hpp

@@ -71,6 +71,8 @@ class SwitchProGamepadInputReport : public hid::report::base<hid::report::type::
   using Gyroscope = espp::gamepad::Gyroscope;
 
 protected:
+#pragma pack(push, 1)
+
   // union for the input report data
   union {
     // struct for the input report and follow-up data such as IMU or command
@@ -130,14 +132,14 @@ class SwitchProGamepadInputReport : public hid::report::base<hid::report::type::
               uint16_t joy_ly : 12;
               uint16_t joy_rx : 12;
               uint16_t joy_ry : 12;
-            } __attribute__((packed));
-          } __attribute__((packed));
+            };
+          };
           // Byte 11: Vibrator input report.
           //          Decides if next vibration pattern should be sent.
           uint8_t vibrator_input_report;
-        } __attribute__((packed)); // input report data struct
+        }; // input report data struct
         uint8_t raw_input_report[12];
-      } __attribute__((packed)); // input report data union
+      }; // input report data union
       // Union for post-input report data such as IMU or command replies
       union {
         // for report IDs 0x30, 0x31, 0x32, 0x33, this is 6-axis data. 3 frames of 2
@@ -155,25 +157,27 @@ class SwitchProGamepadInputReport : public hid::report::base<hid::report::type::
               // Frame 2
               Accelerometer acc_2;
               Gyroscope gyro_2;
-            } __attribute__((packed));
-          } __attribute__((packed));
-        } __attribute__((packed)); //
+            };
+          };
+        }; //
         // 0x21 subcommand reply data; max len 35
         struct {
           uint8_t subcmd_ack;
           uint8_t subcmd_id;
           uint8_t subcmd_reply[35];
-        } __attribute__((packed));
+        };
         // TODO: for report ID 0x23, this is NFC/IR MCU FW update input report (max len 37)
         //
         // TODO: for report id 0x31, there are aditional 313 bytes of NFC/IR data input
         // after this.
-      } __attribute__((packed)); // data union
-    } __attribute__((packed));   // input report data struct
+      }; // data union
+    };   // input report data struct
     // this will ensure we always have enough space for the largest report
     // without having padding bytes defined anywhere.
     uint8_t raw_report[63];
-  } __attribute__((packed));
+  };
+
+#pragma pack(pop)
 
   static constexpr size_t num_data_bytes = 63;
 
@@ -306,7 +310,7 @@ class SwitchProGamepadInputReport : public hid::report::base<hid::report::type::
   constexpr void set_left_trigger(float value) { set_trigger_axis(0, value); }
 
   /// Set the right trigger value
-  /// @param value The value to set the right trigger to.
+  /// @param pressed Whether the right trigger is pressed or not
   constexpr void set_left_trigger(bool pressed) { btn_zl = pressed; }
 
   /// Set the right trigger value
@@ -315,7 +319,7 @@ class SwitchProGamepadInputReport : public hid::report::base<hid::report::type::
   constexpr void set_right_trigger(float value) { set_trigger_axis(1, value); }
 
   /// Set the right trigger value
-  /// @param value The value to set the right trigger to.
+  /// @param pressed Whether the right trigger is pressed or not
   constexpr void set_right_trigger(bool pressed) { btn_zr = pressed; }
 
   /// Set the brake trigger value

components/i2c/include/i2c.hpp

@@ -3,7 +3,7 @@
 #include <sdkconfig.h>
 
 // Only include this header if the legacy API is selected
-#if defined(CONFIG_ESPP_I2C_USE_LEGACY_API) || defined(__DOXYGEN__)
+#if defined(CONFIG_ESPP_I2C_USE_LEGACY_API) || defined(_DOXYGEN_)
 
 #include <mutex>
 #include <vector>