From e1a0714c3f77be0124635f3263ceba951f6fa027 Mon Sep 17 00:00:00 2001 From: "Guenther, Karsten (RDS-RM)" Date: Wed, 3 Jan 2024 14:48:36 +0100 Subject: [PATCH] Add support for variant and component reports --- .vscode/extensions.json | 35 +++++----- conf.py | 17 +++-- coverage.rst | 4 -- {src/spled/doc => doc}/ai_example/index.rst | 0 doc/common/sw_architecture/index.rst | 31 -------- doc/common/variants/index.rst | 23 ------ doc/components/index.rst | 23 ++++++ .../customer_requirements/index.rst | 70 +++++++++---------- doc/index.rst | 9 --- .../_figures/feature_model.svg | 0 .../_figures/spled.drawio | 0 .../_figures/sw_arch_component_diagram.svg | 0 doc/software_architecture/index.rst | 31 +++++++- doc/software_requirements/index.rst | 7 -- doc/test_report_template.txt | 6 +- doc/variants/index.rst | 26 +++++++ index.rst | 43 ++++++++++-- src/brightness_controller/CMakeLists.txt | 2 +- src/brightness_controller/doc/index.rst | 4 +- src/console_interface/CMakeLists.txt | 2 +- src/keyboard_interface/CMakeLists.txt | 2 +- src/keyboard_interface/doc/index.rst | 4 +- src/light_controller/CMakeLists.txt | 2 +- src/light_controller/doc/index.rst | 4 +- src/main_control_knob/CMakeLists.txt | 2 +- src/main_control_knob/doc/index.rst | 4 +- src/power_signal_processing/CMakeLists.txt | 2 +- src/power_signal_processing/doc/index.rst | 4 +- src/rte/CMakeLists.txt | 2 +- src/spled/CMakeLists.txt | 2 +- src/spled/doc/index.rst | 10 --- 31 files changed, 199 insertions(+), 172 deletions(-) delete mode 100644 coverage.rst rename {src/spled/doc => doc}/ai_example/index.rst (100%) delete mode 100644 doc/common/sw_architecture/index.rst delete mode 100644 doc/common/variants/index.rst create mode 100644 doc/components/index.rst rename doc/{common => }/customer_requirements/index.rst (98%) delete mode 100644 doc/index.rst rename doc/{common/sw_architecture => software_architecture}/_figures/feature_model.svg (100%) rename doc/{common/sw_architecture => software_architecture}/_figures/spled.drawio (100%) rename doc/{common/sw_architecture => software_architecture}/_figures/sw_arch_component_diagram.svg (100%) delete mode 100644 doc/software_requirements/index.rst create mode 100644 doc/variants/index.rst delete mode 100644 src/spled/doc/index.rst diff --git a/.vscode/extensions.json b/.vscode/extensions.json index f28553f..af72378 100644 --- a/.vscode/extensions.json +++ b/.vscode/extensions.json @@ -1,18 +1,19 @@ { - "recommendations": [ - "mhutchie.git-graph", - "ms-vscode.cmake-tools", - "twxs.cmake", - "ms-vscode.cpptools", - "ms-vscode.cpptools-themes", - "visualstudioexptteam.intellicode-api-usage-examples", - "visualstudioexptteam.vscodeintellicode", - "haugerbr.project-tasks", - "avengineers.show-link-list", - "ms-python.vscode-pylance", - "ms-python.python", - "donjayamanne.python-environment-manager", - "felipecaputo.git-project-manager", - "ms-vscode.powershell" - ] -} + "recommendations": [ + "mhutchie.git-graph", + "ms-vscode.cmake-tools", + "twxs.cmake", + "ms-vscode.cpptools", + "ms-vscode.cpptools-themes", + "visualstudioexptteam.intellicode-api-usage-examples", + "visualstudioexptteam.vscodeintellicode", + "haugerbr.project-tasks", + "avengineers.show-link-list", + "ms-python.vscode-pylance", + "ms-python.python", + "donjayamanne.python-environment-manager", + "felipecaputo.git-project-manager", + "ms-vscode.powershell", + "waderyan.gitblame" + ] +} \ No newline at end of file diff --git a/conf.py b/conf.py index 17d8564..fb4529e 100644 --- a/conf.py +++ b/conf.py @@ -29,7 +29,7 @@ "**/test_results.rst", # We renamed this file, but nobody deletes it. ] -include_patterns = ["index.rst", "coverage.rst", "definitions.rst", "doc/**"] +include_patterns = ["index.rst", "doc/**"] # configuration of built-in stuff ########################################### # @see https://www.sphinx-doc.org/en/master/usage/configuration.html @@ -164,14 +164,18 @@ def tr_link(app, need, needs, first_option_name, second_option_name, *args, **kw "results": "[[tr_link('title', 'case')]]", } +# Provide all config values to jinja +html_context = { + "build_config": {}, + "config": {}, +} + # Check if the SPHINX_BUILD_CONFIGURATION_FILE environment variable exists # and if so, load the JSON file and set the 'html_context' variable if "SPHINX_BUILD_CONFIGURATION_FILE" in os.environ: with open(os.environ["SPHINX_BUILD_CONFIGURATION_FILE"], "r") as file: - html_context = json.load(file) - include_patterns.extend(html_context.get("include_patterns", [])) - -html_context["config"] = {} + html_context["build_config"] = json.load(file) + include_patterns.extend(html_context["build_config"].get("include_patterns", [])) # Check if the SPHINX_BUILD_CONFIGURATION_FILE environment variable exists # and if so, load the JSON file and set the 'html_context' variable @@ -179,9 +183,8 @@ def tr_link(app, need, needs, first_option_name, second_option_name, *args, **kw with open(os.environ["AUTOCONF_JSON_FILE"], "r") as file: html_context["config"] = json.load(file)["features"] - if "VARIANT" in os.environ: - html_context["config"]["variant"] = os.environ["VARIANT"] + html_context["build_config"]["variant"] = os.environ["VARIANT"] def rstjinja(app, docname, source): diff --git a/coverage.rst b/coverage.rst deleted file mode 100644 index d5a7dc7..0000000 --- a/coverage.rst +++ /dev/null @@ -1,4 +0,0 @@ -Code Coverage -============= - -`Report <../coverage/index.html>`_ diff --git a/src/spled/doc/ai_example/index.rst b/doc/ai_example/index.rst similarity index 100% rename from src/spled/doc/ai_example/index.rst rename to doc/ai_example/index.rst diff --git a/doc/common/sw_architecture/index.rst b/doc/common/sw_architecture/index.rst deleted file mode 100644 index bdd0a4b..0000000 --- a/doc/common/sw_architecture/index.rst +++ /dev/null @@ -1,31 +0,0 @@ -Software Architecture -===================== - -Components ----------- - -.. image:: _figures/sw_arch_component_diagram.svg - -Feature Model -------------- - -.. image:: _figures/feature_model.svg - - -* BlinkRate - * None - * Fixed - * Music-adjusted - -* Color - * Fixed - * Randomized - * Multiple predefined - -* Transition - * Smooth - * Immediate - -* Brightness - * Fixed - * Adjustable diff --git a/doc/common/variants/index.rst b/doc/common/variants/index.rst deleted file mode 100644 index b707bf5..0000000 --- a/doc/common/variants/index.rst +++ /dev/null @@ -1,23 +0,0 @@ -Variants -======== - -* Disco Light - - * Blink Rate: Music-adjusted - * Color: User-defined or randomized - * Transition: Immediate - * Brightness: Medium to High - -* Sleep Light - - * Blink Rate: None (constant light) - * Color: Fixed (e.g., Warm White) - * Transition: None - * Brightness: Low - -* Spa Light - - * Blink Rate: Slow - * Color: Multiple predefined colors - * Transition: Smooth - * Brightness: Medium diff --git a/doc/components/index.rst b/doc/components/index.rst new file mode 100644 index 0000000..eb88506 --- /dev/null +++ b/doc/components/index.rst @@ -0,0 +1,23 @@ +Components +========== + +{% for component_info in build_config.components_info %} +{% if component_info.has_docs %} + +{{ component_info.long_name }} +-------------------- + +.. toctree:: + :maxdepth: 2 + + /{{ component_info.path }}/doc/index +{% if component_info.has_tests %} + /{{ component_info.output_dir }}/unit_test_spec + /{{ component_info.output_dir }}/unit_test_results + /{{ component_info.output_dir }}/doxygen/html/index + /{{ component_info.output_dir }}/coverage +{% endif %} + + +{% endif %} +{% endfor %} diff --git a/doc/common/customer_requirements/index.rst b/doc/customer_requirements/index.rst similarity index 98% rename from doc/common/customer_requirements/index.rst rename to doc/customer_requirements/index.rst index 2c537dc..f7252d1 100644 --- a/doc/common/customer_requirements/index.rst +++ b/doc/customer_requirements/index.rst @@ -1,35 +1,35 @@ -Customer Requirements -===================== - - -Customer A - Disco Light ------------------------- - -Customer A requests a Disco Light that shall offer an ambient lighting experience that resonates with the rhythm of the surroundings. - -* RQ-1: The lighting shall automatically sync with any ambient music, adjusting its blink rate to match the beats or rhythm. -* RQ-2: Users shall have the freedom to choose a specific color for the light. However, in the absence of a user-defined color, the software shall delight the user with randomized colors, ensuring an authentic disco experience. -* RQ-3: As the essence of a disco environment is dynamic and lively, light transitions shall happen instantaneously without any lag. -* RQ-4: The illumination provided shall be vibrant and noticeable, ranging from medium to high levels to keep up with the lively ambiance of disco settings. - - -Customer B - Sleep Light ------------------------- - -Customer B requests a sleep light offering an ambient lighting experience that facilitate a calm and restful environment. - -* RQ-1: The light emitted shall be constant without any blink, ensuring a non-disruptive environment for rest. -* RQ-2: Color of the light shall be fixed to a warm white, known for its soothing and calming properties. -* RQ-3: The brightness of the light shall be adjustable. -* RQ-4: The light color shall be blue. - - -Customer C - Spa Light ----------------------- - -Customer C requests a spa light encapsulating a tranquil and rejuvenating experience, reminiscent of real-world spa environments. - -* RQ-1: The light shall have a slow, rhythmic blink that gives a sensation of calm and peace. -* RQ-2: Instead of a single color, the lighting shall cycle through multiple predefined colors that are commonly associated with relaxation and tranquility. -* RQ-3: Transitions between colors shall be smooth and seamless, ensuring a continuous flow of relaxation. -* RQ-4: The brightness of the light shall be adjustable. +Customer Requirements +===================== + + +Customer A - Disco Light +------------------------ + +Customer A requests a Disco Light that shall offer an ambient lighting experience that resonates with the rhythm of the surroundings. + +* RQ-1: The lighting shall automatically sync with any ambient music, adjusting its blink rate to match the beats or rhythm. +* RQ-2: Users shall have the freedom to choose a specific color for the light. However, in the absence of a user-defined color, the software shall delight the user with randomized colors, ensuring an authentic disco experience. +* RQ-3: As the essence of a disco environment is dynamic and lively, light transitions shall happen instantaneously without any lag. +* RQ-4: The illumination provided shall be vibrant and noticeable, ranging from medium to high levels to keep up with the lively ambiance of disco settings. + + +Customer B - Sleep Light +------------------------ + +Customer B requests a sleep light offering an ambient lighting experience that facilitate a calm and restful environment. + +* RQ-1: The light emitted shall be constant without any blink, ensuring a non-disruptive environment for rest. +* RQ-2: Color of the light shall be fixed to a warm white, known for its soothing and calming properties. +* RQ-3: The brightness of the light shall be adjustable. +* RQ-4: The light color shall be blue. + + +Customer C - Spa Light +---------------------- + +Customer C requests a spa light encapsulating a tranquil and rejuvenating experience, reminiscent of real-world spa environments. + +* RQ-1: The light shall have a slow, rhythmic blink that gives a sensation of calm and peace. +* RQ-2: Instead of a single color, the lighting shall cycle through multiple predefined colors that are commonly associated with relaxation and tranquility. +* RQ-3: Transitions between colors shall be smooth and seamless, ensuring a continuous flow of relaxation. +* RQ-4: The brightness of the light shall be adjustable. diff --git a/doc/index.rst b/doc/index.rst deleted file mode 100644 index 3490084..0000000 --- a/doc/index.rst +++ /dev/null @@ -1,9 +0,0 @@ -Project Report -############## - -.. toctree:: - :maxdepth: 1 - :caption: Contents: - - software_requirements/index - software_architecture/index \ No newline at end of file diff --git a/doc/common/sw_architecture/_figures/feature_model.svg b/doc/software_architecture/_figures/feature_model.svg similarity index 100% rename from doc/common/sw_architecture/_figures/feature_model.svg rename to doc/software_architecture/_figures/feature_model.svg diff --git a/doc/common/sw_architecture/_figures/spled.drawio b/doc/software_architecture/_figures/spled.drawio similarity index 100% rename from doc/common/sw_architecture/_figures/spled.drawio rename to doc/software_architecture/_figures/spled.drawio diff --git a/doc/common/sw_architecture/_figures/sw_arch_component_diagram.svg b/doc/software_architecture/_figures/sw_arch_component_diagram.svg similarity index 100% rename from doc/common/sw_architecture/_figures/sw_arch_component_diagram.svg rename to doc/software_architecture/_figures/sw_arch_component_diagram.svg diff --git a/doc/software_architecture/index.rst b/doc/software_architecture/index.rst index 79fd4ff..bdd0a4b 100644 --- a/doc/software_architecture/index.rst +++ b/doc/software_architecture/index.rst @@ -1,2 +1,31 @@ Software Architecture -##################### \ No newline at end of file +===================== + +Components +---------- + +.. image:: _figures/sw_arch_component_diagram.svg + +Feature Model +------------- + +.. image:: _figures/feature_model.svg + + +* BlinkRate + * None + * Fixed + * Music-adjusted + +* Color + * Fixed + * Randomized + * Multiple predefined + +* Transition + * Smooth + * Immediate + +* Brightness + * Fixed + * Adjustable diff --git a/doc/software_requirements/index.rst b/doc/software_requirements/index.rst deleted file mode 100644 index 4ac4da2..0000000 --- a/doc/software_requirements/index.rst +++ /dev/null @@ -1,7 +0,0 @@ -Software Requirements -##################### - -.. req:: Requirement 001 - :status: open - - ... \ No newline at end of file diff --git a/doc/test_report_template.txt b/doc/test_report_template.txt index bc33e55..a858ac0 100644 --- a/doc/test_report_template.txt +++ b/doc/test_report_template.txt @@ -2,7 +2,7 @@ Passed test cases ----------------- .. needtable:: - :filter: type == '{case_need}' and 'passed' == result + :filter: '{id}' in tags and type == '{case_need}' and 'passed' == result :columns: id, title, is resulted from :style: table @@ -10,7 +10,7 @@ Failed test cases ----------------- .. needtable:: - :filter: type == '{case_need}' and 'failure' == result + :filter: '{id}' in tags and type == '{case_need}' and 'failure' == result :columns: id, title, is resulted from :style: table @@ -18,7 +18,7 @@ Skipped test cases ------------------ .. needtable:: - :filter: type == '{case_need}' and 'skipped' == result + :filter: '{id}' in tags and type == '{case_need}' and 'skipped' == result :columns: id, title, is resulted from :style: table diff --git a/doc/variants/index.rst b/doc/variants/index.rst new file mode 100644 index 0000000..cfdec60 --- /dev/null +++ b/doc/variants/index.rst @@ -0,0 +1,26 @@ +Variants +======== + +Disco Light +----------- + +* Blink Rate: Music-adjusted +* Color: User-defined or randomized +* Transition: Immediate +* Brightness: Medium to High + +Sleep Light +----------- + +* Blink Rate: None (constant light) +* Color: Fixed (e.g., Warm White) +* Transition: None +* Brightness: Low + +Spa Light +--------- + +* Blink Rate: Slow +* Color: Multiple predefined colors +* Transition: Smooth +* Brightness: Medium diff --git a/index.rst b/index.rst index fb4da24..c55c261 100644 --- a/index.rst +++ b/index.rst @@ -1,7 +1,36 @@ -Software Component Report -========================= - -**Variant:** {{ config.variant }} - -{{ generated_rst_content }} - coverage +{% if build_config.component_info %} + +Software Component Report +######################### + +| **Variant:** {{ build_config.variant }} +| **Component:** {{ build_config.component_info.long_name }} + +.. toctree:: + :maxdepth: 2 + + {{ build_config.component_info.path }}/doc/index +{% if build_config.component_info.has_tests %} + {{ build_config.component_info.output_dir }}/unit_test_spec + {{ build_config.component_info.output_dir }}/unit_test_results + {{ build_config.component_info.output_dir }}/doxygen/html/index + {{ build_config.component_info.output_dir }}/coverage +{% endif %} + +{% else %} + +Variant Report +############## + +**Variant:** {{ build_config.variant }} + +.. toctree:: + :maxdepth: 1 + :caption: Contents + + doc/customer_requirements/index + doc/software_architecture/index + doc/variants/index + doc/components/index + +{% endif %} diff --git a/src/brightness_controller/CMakeLists.txt b/src/brightness_controller/CMakeLists.txt index d0c2cd9..a6e9e84 100644 --- a/src/brightness_controller/CMakeLists.txt +++ b/src/brightness_controller/CMakeLists.txt @@ -1,3 +1,3 @@ spl_add_source(src/brightness_controller.c) spl_add_test_source(test/test_brightness_controller.cc) -spl_create_component() +spl_create_component(LONG_NAME "Brightness Controller") diff --git a/src/brightness_controller/doc/index.rst b/src/brightness_controller/doc/index.rst index 38ae5ed..44d9b6b 100644 --- a/src/brightness_controller/doc/index.rst +++ b/src/brightness_controller/doc/index.rst @@ -1,5 +1,5 @@ -Software Detailed Design for Brightness Controller -================================================== +Software Detailed Design +======================== .. contents:: Table of Contents :depth: 2 diff --git a/src/console_interface/CMakeLists.txt b/src/console_interface/CMakeLists.txt index 7fddede..8516c9a 100644 --- a/src/console_interface/CMakeLists.txt +++ b/src/console_interface/CMakeLists.txt @@ -1,2 +1,2 @@ spl_add_source(src/console_interface.c) -spl_create_component() +spl_create_component(LONG_NAME "Console Interface") diff --git a/src/keyboard_interface/CMakeLists.txt b/src/keyboard_interface/CMakeLists.txt index 99e53f7..9ffbd6d 100644 --- a/src/keyboard_interface/CMakeLists.txt +++ b/src/keyboard_interface/CMakeLists.txt @@ -1,3 +1,3 @@ spl_add_source(src/keyboard_interface.c) spl_add_test_source(test/test_keyboard_interface.cc) -spl_create_component() +spl_create_component(LONG_NAME "Keyboard Interface") diff --git a/src/keyboard_interface/doc/index.rst b/src/keyboard_interface/doc/index.rst index cc7c87e..89b7722 100644 --- a/src/keyboard_interface/doc/index.rst +++ b/src/keyboard_interface/doc/index.rst @@ -1,5 +1,5 @@ -Software Detailed Design for Keyboard Interface -=============================================== +Software Detailed Design +======================== This module interfaces with the keyboard and detects specific key presses, primarily focusing on the TARGET_KEY. diff --git a/src/light_controller/CMakeLists.txt b/src/light_controller/CMakeLists.txt index 4068adf..902711b 100644 --- a/src/light_controller/CMakeLists.txt +++ b/src/light_controller/CMakeLists.txt @@ -1,3 +1,3 @@ spl_add_source(src/light_controller.c) spl_add_test_source(test/test_light_controller.cc) -spl_create_component() +spl_create_component(LONG_NAME "Light Controller") diff --git a/src/light_controller/doc/index.rst b/src/light_controller/doc/index.rst index 836b655..a4bfee8 100644 --- a/src/light_controller/doc/index.rst +++ b/src/light_controller/doc/index.rst @@ -1,5 +1,5 @@ -Software Detailed Design for Light Controller Component -======================================================= +Software Detailed Design +======================== .. contents:: Table of Contents :depth: 2 diff --git a/src/main_control_knob/CMakeLists.txt b/src/main_control_knob/CMakeLists.txt index 722ba1f..716b07b 100644 --- a/src/main_control_knob/CMakeLists.txt +++ b/src/main_control_knob/CMakeLists.txt @@ -1,3 +1,3 @@ spl_add_source(src/main_control_knob.c) spl_add_test_source(test/test_main_control_knob.cc) -spl_create_component() +spl_create_component(LONG_NAME "Main Control Knob") diff --git a/src/main_control_knob/doc/index.rst b/src/main_control_knob/doc/index.rst index fa9dc9c..c0ca324 100644 --- a/src/main_control_knob/doc/index.rst +++ b/src/main_control_knob/doc/index.rst @@ -1,5 +1,5 @@ -Software Detailed Design for Main Control Knob Component -======================================================== +Software Detailed Design +======================== The main control knob component is responsible for calculating a value between 0 and 100 percent depending on the user's input. diff --git a/src/power_signal_processing/CMakeLists.txt b/src/power_signal_processing/CMakeLists.txt index 47476ef..b7448ea 100644 --- a/src/power_signal_processing/CMakeLists.txt +++ b/src/power_signal_processing/CMakeLists.txt @@ -1,3 +1,3 @@ spl_add_source(src/power_signal_processing.c) spl_add_test_source(test/test_power_signal_processing.cc) -spl_create_component() +spl_create_component(LONG_NAME "Power Signal Processing") diff --git a/src/power_signal_processing/doc/index.rst b/src/power_signal_processing/doc/index.rst index 1163d3d..2e076ca 100644 --- a/src/power_signal_processing/doc/index.rst +++ b/src/power_signal_processing/doc/index.rst @@ -1,5 +1,5 @@ -Software Detailed Design for Power Signal Processing -==================================================== +Software Detailed Design +======================== This module is responsible for processing power signals based on key presses. diff --git a/src/rte/CMakeLists.txt b/src/rte/CMakeLists.txt index 4f1e1ae..3f4479b 100644 --- a/src/rte/CMakeLists.txt +++ b/src/rte/CMakeLists.txt @@ -1,2 +1,2 @@ spl_add_source(src/rte.c) -spl_create_component() +spl_create_component(LONG_NAME "Run Time Environment") diff --git a/src/spled/CMakeLists.txt b/src/spled/CMakeLists.txt index 1157cd7..ccd94d1 100644 --- a/src/spled/CMakeLists.txt +++ b/src/spled/CMakeLists.txt @@ -1,3 +1,3 @@ spl_add_source(src/spled.c) spl_add_test_source(test/test_spled.cc) -spl_create_component() +spl_create_component(LONG_NAME "SPLED") diff --git a/src/spled/doc/index.rst b/src/spled/doc/index.rst deleted file mode 100644 index 6474900..0000000 --- a/src/spled/doc/index.rst +++ /dev/null @@ -1,10 +0,0 @@ -SPLed Documentation -################### - -.. toctree:: - - /doc/common/customer_requirements/index.rst - /doc/common/sw_architecture/index.rst - /doc/common/variants/index.rst - ai_example/index.rst -