Add user manuals for time module#133
Draft
ryan-steel wants to merge 7 commits into
Draft
Conversation
It includes - An overall architecture introduction and a guide for choosing the right clock. - A detailed API description covering basic usage, lifecycle management, advanced subscriptions, and unit-testing patterns. - A dedicated integration guide for system integrators. - A troubleshooting guide for diagnosing common runtime issues.
…rib/score_inc_time into docs/ryan-steel-LudwigAtBosch-user-manual
ryan-steel
had a problem deploying
to
workflow-approval
July 17, 2026 09:50 — with 
GitHub Actions
Error
GitHub Actions
Error
ryan-steel
had a problem deploying
to
workflow-approval
July 17, 2026 09:50 — with
GitHub Actions
Error
GitHub Actions
Error
License Check Results🚀 The license check job ran with the Bazel command: bazel run //:license-checkStatus: Click to expand output |
|
The created documentation from the pull request is available at: docu-html |
ryan-steel
force-pushed
the
docs/ryan-steel-LudwigAtBosch-user-manual
branch
from
July 17, 2026 10:05
ff777e2 to
1cb0e96
Compare
ryan-steel
requested a deployment
to
workflow-approval
July 17, 2026 10:05 — with
GitHub Actions
Waiting
GitHub Actions
Waiting
ryan-steel
requested a deployment
to
workflow-approval
July 17, 2026 10:05 — with
GitHub Actions
Waiting
GitHub Actions
Waiting
This was referenced Jul 17, 2026
There was a problem hiding this comment.
Pull request overview
Adds user-facing Sphinx documentation for the S-CORE time module (module manual + component manuals), and updates the documentation build layout to allow building docs that live in component subdirectories.
Changes:
- Added new user manuals for the time library, TimeSlave, and TimeDaemon (including examples and API usage chapters).
- Added module-level manual and troubleshooting guide under
docs/manuals/, and linked manuals/features from the rootindex.rst. - Switched the Sphinx/Bazel docs entry-point to the repository root via
source_dir = "."andinclude_patternsfiltering.
Reviewed changes
Copilot reviewed 19 out of 21 changed files in this pull request and generated 5 comments.
Show a summary per file
| File | Description |
|---|---|
| score/time/docs/manuals/user_manual.rst | Time library user manual with clock selection, API toctrees, build integration, and runtime requirements links. |
| score/time/docs/manuals/examples/index.rst | Index page describing time examples and how to build/run them. |
| score/time/docs/manuals/examples/basic_clocks.rst | Manual page documenting basic clock examples and common patterns. |
| score/time/docs/manuals/examples/vehicle_time.rst | Manual page documenting the VehicleTime example, output, tests, and Bazel target structure. |
| score/time/docs/manuals/api_description/api_usage.rst | API usage guide for polling VehicleTime and handling reliability. |
| score/time/docs/manuals/api_description/lifecycle.rst | Lifecycle management guide (Init/WaitUntilAvailable/IsAvailable). |
| score/time/docs/manuals/api_description/testing_guide.rst | Testing guide describing clock overrides and test patterns. |
| score/time/docs/manuals/api_description/advanced_api.rst | Advanced API guide for subscribing to low-level PTP events and threading considerations. |
| score/time_slave/docs/manuals/user_manual.rst | TimeSlave component user manual (overview, configuration toctree, runtime requirements). |
| score/time_slave/docs/manuals/config/configuration_guide.rst | TimeSlave configuration guide and CLI options/defaults. |
| score/time_slave/docs/index.rst | Component index trimmed to a minimal toctree entry. |
| score/time_daemon/docs/manuals/user_manual.rst | TimeDaemon component user manual (overview, configuration toctree, runtime requirements). |
| score/time_daemon/docs/manuals/config/configuration_guide.rst | TimeDaemon configuration guide (no external config; shared memory details). |
| index.rst | Root documentation index updated to link into docs/features and docs/manuals, plus component documentation links. |
| docs/manuals/index.rst | Manuals index added to include the module user manual. |
| docs/manuals/user_manual.rst | Module-level user manual describing integration, deployment, and links to component manuals. |
| docs/manuals/troubleshooting_guide.rst | Module troubleshooting guide (reliability/availability issues, IPC mismatch, logging contexts). |
| conf.py | Sphinx include filtering added; templates path adjusted. |
| BUILD | Docs rule updated to build with source_dir = "." (root-based Sphinx entry). |
Comments suppressed due to low confidence (2)
conf.py:62
- templates_path points to "docs/templates", but that directory doesn’t exist in the repository. If templates aren’t used, set templates_path to an empty list to avoid confusion and potential build warnings.
index.rst:52 - The "Component Documentation" toctree only links to TimeSlave’s component index even though the docs set added manuals for multiple components. This makes the section title misleading and makes it harder to navigate directly to the manuals.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+109
to
+112
| 3. Include headers and compile your code | ||
|
|
||
| .. For detailed API usage and examples, refer to the :doc:`/score/time/docs/manuals/user_manual`. | ||
Comment on lines
+44
to
+45
| Component Manuals | ||
| ----------------- |
Comment on lines
+116
to
+119
| The ``time`` module requires two system daemons to be running. These processes must be managed by the system's service manager (e.g., `systemd` on Linux, or a launch script on QNX). | ||
|
|
||
| .. For detailed configuration of each daemon (OS privileges, network configuration, command-line arguments), refer to the :ref:`component_manuals<component manuals>` linked above. | ||
Comment on lines
+33
to
+57
| #include "score/time/clock/src/clock_backend_mock.h" | ||
| #include "score/time/vehicle_time.h" | ||
| #include <chrono> | ||
| #include <memory> | ||
|
|
||
| // A helper class to manage a fake clock backend in tests. | ||
| class ClockTestFactory { | ||
| public: | ||
| // Creates the backend and returns a shared_ptr to it. | ||
| // This backend is then passed to the ScopedClockOverride. | ||
| std::shared_ptr<score::time::test_utils::ClockBackendMock<score::time::VehicleTime>> | ||
| CreateFakeClock() { | ||
| fake_clock_backend_ = std::make_shared<score::time::test_utils::ClockBackendMock<score::time::VehicleTime>>(); | ||
| return fake_clock_backend_; | ||
| } | ||
|
|
||
| // Advances the time on the created fake clock. | ||
| void AdvanceTime(std::chrono::nanoseconds duration) { | ||
| // We simulate a monotonic clock by shifting the offset of the mock | ||
| // to return a progressively advanced timestamp on every subsequent call. | ||
| current_time_ += duration; | ||
| ON_CALL(*fake_clock_backend_, Now()) | ||
| .WillByDefault(testing::Return(score::time::TimeSnapshot<score::time::VehicleTime>( | ||
| score::time::VehicleTime::time_point(current_time_)))); | ||
| } |
Comment on lines
+54
to
+57
| **Cause & Solution:** | ||
|
|
||
| Understanding Log Messages | ||
| ========================== |
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
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.
Improvement
Adds user-facing documentation for S-CORE time module and its key components.
Description
Added module manuals for integration and troubleshooting
Added component manuals for time library, TimeSlave, and TimeDaemon
Added main index links so users can navigate module and component docs
For building with docs in component subdirectories:
Further work
I don't like that the root index.rst references only time_daemon but #123 already adds an update to the document.
Related Ticket
closes #125 (improvement ticket)