fix(docs): pre-create Doxybook output directories #75
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
…ents (#74) * Fix: C++20 Build Compatibility - Proto Syntax and Comment Issues (#72) * fix namespace conflict * fix namespace (#69) * Fix: Improve Debian package upgrade robustness - separate upgrade/remove cases and make ldconfig non-fatal * C++ modernisation * GoogleDiagnosticsVendorExtensionMessageId.proto proto set * updated cmake to 3.16 * Protobuf v30 fetch and build * cmake fixes fot v30 * empty dir fix * cmake fix#2 * fix cmake * path fix * Add protobuf source include path for runtime_version.h * CMake: prefer fetched Protobuf, add src include to aasdk, link to protobuf::libprotobuf * Fix: Use modern C++17 namespace syntax consistently Channel.hpp and BluetoothService files now use the scoped namespace syntax (namespace aasdk::channel {) instead of nested declarations. This is consistent with C++17/20 modernization goals and prevents namespace nesting issues. * Fix: Standardize all header namespaces to C++17 scoped syntax This fixes the phantom aasdk::aasdk namespace issue affecting compilation. Changed 31 header files from nested namespace declarations: namespace aasdk { namespace xyz { To modern C++17 scoped syntax: namespace aasdk::xyz { Files affected: - All 19 Messenger headers (IMessenger, Message, Promise, MessageType, etc.) - Common headers (Data, Log) - Error headers (Error, ErrorCode) - IO headers (Promise, IOContextWrapper, PromiseLink) - Channel headers (Promise) - TCP headers (ITCPEndpoint, TCPEndpoint, ITCPWrapper, TCPWrapper) This ensures consistent namespace declarations across all classes and inheritance hierarchies, resolving compiler errors where std::string was treated as aasdk::std::string and similar phantom namespacing issues. * Fix: Correct malformed closing brace in IO/Promise.hpp The namespace conversion created a syntax error with };{ on line 248. This has been corrected to properly close the inner class and maintain correct namespace scoping. * Fix: Complete namespace standardization - add Transport and USB directories Added 30 more header files to namespace standardization: - 7 Transport/*.hpp files: convert to namespace aasdk::transport { - 23 USB/*.hpp files: convert to namespace aasdk::usb { - 1 Common/ModernLogger.hpp: convert to namespace aasdk::common { This completes the comprehensive conversion of ALL 61 header files from nested namespace declarations to modern C++17 scoped syntax. This eliminates the namespace pollution issue where aasdk::io::std and similar phantom namespaces were being created. * fix promise * Fix: Add #include <utility> before boost/asio in all headers to resolve std::exchange compilation errors - Added <utility> header before boost/asio.hpp in 17 header files - Ensures std::exchange is available for boost/asio's awaitable.hpp - Fixes compilation on both trixie and bookworm distros - Applied to Promise, IOContextWrapper, Channel, Messenger, Transport, TCP, USB headers * Trigger CI * fix asio * switch amd onlly * Added docs updater * added docs * Revert "added docs" This reverts commit 8ada9fb. * fix up doc gen * docs: add comprehensive ASCII-safe Doxygen documentation for core AASDK classes Add detailed documentation with ASCII-only characters (no unicode): - Messenger: channel multiplexing, queuing, thread safety, lifecycle - ITransport: async Promise interface, USB/TCP scenarios, 60ms timing - IUSBHub: AOAP protocol, device discovery flow, hotplug handling - IChannel: protocol channels (0-7), channel registry, message flow - USBTransport: AOAP bulk transfers, timeout strategy, error scenarios - TCPTransport: wireless deployment, network topology, reliability Documentation includes: - Purpose and design rationale - Architecture diagrams (ASCII) - Typical message flow scenarios with timing - Thread safety guarantees - Error handling patterns - Configuration/timeout values All text uses ASCII-safe characters (hyphens instead of unicode dashes) for maximum C++ compiler portability. * docs: add comprehensive Doxygen comments to AASDK src/ implementation files - Messenger.cpp: Documented message routing, channel multiplexing, scenario examples - Transport.cpp: Documented frame buffering, size-based flow control - AOAPDevice.cpp: Documented AOAP mode and endpoint management - TCPEndpoint.cpp: Documented wireless Android Auto over WiFi with timing - Channel.cpp: Documented channel multiplexing and isolation - Error.cpp: Documented error handling and promise rejection - Data.cpp: Documented buffer management and zero-copy views - IOContextWrapper.cpp: Documented promise execution context dispatching - MediaBrowserService.cpp: Documented music library browsing and state All comments use ASCII-only characters for C++ compiler compatibility. Each method/class includes intention, scenario examples with timing, and thread safety notes for comprehensive Doxygen documentation generation. * docs: add comprehensive comments to AASDK protobuf message definitions - MessageStatus.proto: Documented all error codes and success statuses - SessionConfiguration.proto: Documented UI config flags with dashboard example - InstrumentClusterInput.proto: Documented steering wheel controls scenario - Service.proto: Documented all Android Auto services with timing example - PhoneInfo.proto: Documented device and session tracking with reconnection - MediaPlaybackStatusService.proto: Documented playback control and metadata flow - NavigationStatusService.proto: Documented turn-by-turn display modes - BluetoothService.proto: Documented hands-free calling and pairing setup - PhoneStatusService.proto: Documented incoming calls and notifications - ControlMessageType.proto: Documented protocol negotiation and lifecycle All comments include intention, realistic scenarios with timing, and use ASCII-only characters for C++ proto parser compatibility. Enables comprehensive Doxygen-generated documentation for protocol understanding. * docs: add comprehensive documentation to additional AASDK src/ files - USBHub.cpp: Documented device hotplug detection and AOAP mode negotiation - USBEndpoint.cpp: Documented USB transfer types and frame framing with timing - TCPWrapper.cpp: Documented async TCP operations and wireless scenarios Completes documentation of core USB and TCP transport implementations with ASCII-only text and realistic scenario examples with millisecond timing. * docs: add comprehensive documentation completion summary Summarises complete Doxygen documentation effort across AASDK: - 28 files documented (6 headers, 12 implementations, 10 protobuf) - 1,257 lines of documentation across 4 commits - ASCII-only for C++ compiler compatibility - Scenario examples with realistic timing - Thread safety and error handling documented - Ready for Doxygen HTML/PDF generation * fix: correct Error message string construction Fix malformed concatenation in Error::Error that left a stray unary plus and broke compilation. Message now includes additional information field properly. * ci: trigger rebuild on feature/c++20 * docs: add comprehensive build status analysis for feature/c++20 * ci: limit non-main/develop branches to amd64 builds for faster cycle time * fix(c++20): disable -pedantic for external dependencies (Abseil, Protobuf) The -pedantic compiler flag was causing compilation failures when building Abseil (LTS 2024-07-22) and Protobuf v30.0 as external FetchContent dependencies. These libraries have valid code that triggers pedantic warnings unrelated to AASDK's codebase. Solution: Temporarily disable -pedantic during FetchContent_MakeAvailable() calls for Abseil and Protobuf, then restore it for AASDK's own source code. This maintains strict compiler checks for our code while allowing external dependencies to build cleanly. Fixes: feature/c++20 build failures on Debian trixie/bookworm * docs: add C++20 pedantic flag fix documentation * fix(c++20): use fetched protoc from FetchContent, not system protoc The build was failing because the aap_protobuf subdirectory was using the system Protobuf v3.21.12 protoc to generate code from Protobuf v30.0 proto files. This causes version mismatch errors (Service.pb.h generation failed). Solution: 1. Set PROTOBUF_PROTOC_EXECUTABLE to point to the built protoc from FetchContent 2. Remove find_package(Protobuf) call that was finding the system version 3. Rely only on the FetchContent-built Protobuf v30.0 This ensures proto files are compiled with the correct protoc version that matches the proto definitions. * Fix: Remove duplicate proto header in Service.proto for protobuf v30.0 compatibility * Fix: Resolve nested comment syntax error in Error.cpp * Fix: Remove duplicate Doxygen @param documentation from Messenger.cpp Doxygen was reporting duplicate @param sections for: - enqueueReceive: channelId and promise parameters - enqueueSend: message and promise parameters Root cause: Documentation existed in both the header file (Messenger.hpp) and implementation file (Messenger.cpp). Standard practice: Detailed API documentation belongs in the header (interface), not the implementation. Removed duplicate doc blocks from .cpp file while preserving complete documentation in .hpp file. Fixes warnings: - Line 60: enqueueReceive duplicate @param channelId, promise - Line 108: enqueueSend duplicate @param message, promise * Improve doxybook2 error handling and debugging in wiki generation script * Add debug output and dependency verification to auto-wiki-docs workflow * feat: Add pkg-config file for better compatibility (#73) * feat: Add pkg-config file for better compatibility - Add aasdk.pc.in template for pkg-config support - Configure and install .pc file to pkgconfig directory - Improves compatibility with build systems that prefer pkg-config - Complements existing CMake config files * fix doxybook path
- Create common category folders (Namespaces, Classes, Files, Modules, Pages) - Avoid 'Failed to open file for writing' errors during Markdown rendering - Ensures wiki generation succeeds when Doxybook does not create parent folders
- Mirror Doxygen XML directory structure under wiki Namespaces output - Prevent Doxybook failures writing Namespaces/d*/.../namespacetesting.md - Keeps previous category mkdirs (Namespaces/Classes/Files/Modules/Pages)
- Move Namespaces tree creation to after Doxygen run so XML directory is present - Prevent Doxybook failing to write Namespaces/d*/... files
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Summary
Fix documentation generation failures caused by Doxybook trying to write into missing category folders.
Changes
Testing
./.github/scripts/docs/generate_wiki_docs.shlocally or via workflow; Doxybook should complete without file write errors.Context
Addresses failing run: https://github.com/opencardev/aasdk/actions/runs/21312047573