feat: add creation of variant docs

.vscode/settings.json

@@ -28,6 +28,5 @@
     "[python]": {
         "editor.defaultFormatter": "ms-python.black-formatter"
     },
-    "esbonio.sphinx.confDir": "",
     "cmake.configureOnOpen": false
 }

.vscode/tasks.json

@@ -39,7 +39,7 @@
     },
     {
       "label": "clean build docs",
-      "command": "pipenv run sphinx-build -a docs out/docs/html",
+      "command": "pipenv run sphinx-build -E docs out/docs/html",
       "type": "shell",
       "presentation": {
         "reveal": "always"

Pipfile

@@ -4,28 +4,35 @@ verify_ssl = true
 name = "pypi"
 
 [packages]
-conan = {version="==1.59.0"}
 cookiecutter = {version="==2.1.1"}
 gcovr = "*"
 hammocking = "*"
 kconfiglib = "*"
 
 [dev-packages]
+jinja2 = "*"
 pytest = "*"
+pytest-env = "*"
 pytest-cov = "*"
-pipenv = "*"
+testfixtures = "*"
+junitparser = "*"
+mashumaro = "*"
+loguru = "*"
+black = "*"
 m2r = "*"
 flake8 = "*"
 sphinx = "*"
 sphinx-rtd-theme = "*"
 sphinxcontrib-mermaid = "*"
 sphinx-needs = "*"
 sphinx-test-reports = "*"
-sphinxcontrib-plantuml = "*"
 doxysphinx = "*"
 sphinx-rtd-size = "*"
+sphinxcontrib-datatemplates = "*"
+sphinxcontrib-plantuml = "*"
 sphinx-copybutton = "*"
 sphinx-new-tab-link = "*"
+pipenv = "*"
 
 [requires]
 python_version = "3.11"

cmake/spl.cmake

@@ -71,8 +71,6 @@ elseif(BUILD_KIT STREQUAL test)
     list(APPEND CMAKE_CTEST_ARGUMENTS "--output-on-failure")
 
     add_custom_target(coverage)
-    add_custom_target(docs)
-    add_custom_target(reports)
 else()
     message(FATAL_ERROR "Invalid BUILD_KIT selected!")
 endif(BUILD_KIT STREQUAL prod)
@@ -81,10 +79,11 @@ endif(BUILD_KIT STREQUAL prod)
 cmake_language(DEFER DIRECTORY ${CMAKE_SOURCE_DIR} CALL _spl_hook_end_of_configure())
 
 function(_spl_hook_end_of_configure)
-    _spl_coverage_create_overall_report()
-
-    if(CONAN__REQUIRES OR CONAN__BUILD_REQUIRES)
-    endif() # CONAN__REQUIRES
+    if(BUILD_KIT STREQUAL test)
+        _spl_coverage_create_overall_report()
+        _spl_create_docs_target()
+        _spl_create_reports_target()
+    endif(BUILD_KIT STREQUAL test)
 endfunction(_spl_hook_end_of_configure)
 
 # # This is one possibility to open guiconfig of kconfiglib. VSCode task is the preferred solution

docs/changelog/index.rst → docs/about/index.rst

@@ -1 +1,4 @@
+📄 About
+********
+
 .. mdinclude:: ../../CHANGELOG.md

docs/features/index.rst

@@ -0,0 +1,19 @@
+✨ Features
+************
+
+Component Report
+----------------
+
+To support the :ref:`component <what_is_a_component>` development, SPL Core provides features to:
+
+- document the component behavior - see :ref:`How to create a component detail design <how_to_component_detail_design>`
+- test the component behavior - see :ref:`How to create a component test cases <how_to_component_test_cases>`
+- generate component report with full traceability between documentation, code and tests - see :ref:`Component relevant CMake Targets <component_cmake_targets>`
+
+
+Variant Report
+--------------
+
+To support the :ref:`variant <what_is_a_variant>` development, SPL Core provides features to:
+
+TODO: add variant report description

docs/getting_started/concepts.rst

@@ -4,25 +4,27 @@ Basic Concepts and Naming Conventions
 What is a Software Product Line (SPL)?
 --------------------------------------
 
-An SPL is a software project that contains shared and configurable source code elements known as `components <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-component>`_, which are used to develop several versions of a computer program, also known as `variants <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-variant>`_.
+An SPL is a software project that contains shared and configurable source code elements known as :ref:`components <what_is_a_component>`, which are used to develop several versions of a computer program, also known as :ref:`variants <what_is_a_variant>`.
 
 Think of an SPL like an automotive factory that makes different types of cars.
 Each car is special - some are race cars, some are trucks, and others might be convertibles.
-But they all start from some common `components <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-component>`_ like wheels and engines with different configurations like size and horsepowers.
-Thinking this way, making a new program is like building a new car but faster and easier because we already have the `components <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-component>`_ we need.
+But they all start from some common :ref:`components <what_is_a_component>` like wheels and engines with different configurations like size and horsepowers.
+Thinking this way, making a new program is like building a new car but faster and easier because we already have the :ref:`components <what_is_a_component>` we need.
 
 What is SPL Core?
 -----------------
 
 SPL Core is a tool chain that uses modern `CMake <https://cmake.org/>`_.
-SPL Core supports the concepts and requirements of an SPL to build various software `variants <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-variant>`_ from a common codebase.
+SPL Core supports the concepts and requirements of an SPL to build various software :ref:`variants <what_is_a_variant>` from a common codebase.
+
+.. _what_is_a_variant:
 
 What is a Variant?
 ------------------
 
-A variant is a specific version of the software, consisting of a set of `features <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-feature-model>`_ that meet specific customer requirements.
+A variant is a specific version of the software, consisting of a set of :ref:`features <what_is_a_feature_model>` that meet specific customer requirements.
 
-Think of a variant like choosing different `features <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-feature-model>`_ for your car.
+Think of a variant like choosing different :ref:`features <what_is_a_feature_model>` for your car.
 One car might be red with racing stripes and another might be a blue truck.
 In computer programs, a variant is a version of the program that has something different or special about it, but it's still based on the same basic design.
 It's like customizing your car or program to make it just the way you want it.
@@ -50,8 +52,8 @@ Here is an example of the variants directory with two variants (``my/var1`` and
 
 
 * ``config.cmake`` - variant specific CMake configuration, like the target architecture and toolchain.
-* ``parts.cmake`` - contains the list of `components <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-component>`_ that are part of the variant.
-* ``config.txt`` - this is the `feature <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-feature-model>`_ selection of the variant. It is a KConfig file that contains the selected `features <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-feature-model>`_ of the variant.
+* ``parts.cmake`` - contains the list of :ref:`components <what_is_a_component>` that are part of the variant.
+* ``config.txt`` - this is the :ref:`feature <what_is_a_feature_model>` selection of the variant. It is a KConfig file that contains the selected :ref:`features <what_is_a_feature_model>` of the variant.
 
 .. _what_is_a_component:
 
@@ -107,12 +109,13 @@ Here is an example of the source directory with two components (``src/comp1`` an
 * **Component Definition**
     * The component's ``CMakeLists.txt`` makes the component available using :ref:`spl_create_component <spl_create_component>`.
 
+.. _what_is_a_feature_model:
 
 What is a Feature Model?
 ------------------------
 
 A feature model represents the organization of all potential features in an SPL, showing how they relate and depend on each other.
-This model guides the creation of different SPL `variants <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-variant>`_, ensuring that feature combinations are viable and consistent.
+This model guides the creation of different SPL :ref:`variants <what_is_a_variant>`, ensuring that feature combinations are viable and consistent.
 
 Think of a feature model like a big chart showing all the different features you can choose from to customize your car.
 It tells you which pieces fit together and how you can combine them to make different types of cars.
@@ -123,5 +126,5 @@ In computer programs, a feature model helps us understand all the features (like
 
 If a ``KConfig`` file is present in the root directory, SPL Core will automatically parse it and generate the project configuration.
 
-The `variant <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-variant>`_ specific configuration file is expected in the `variant <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-variant>`_ directory.
-If a ``config.txt`` file is present in the `variant <https://engweb.marquardt.de/sple/spl-core/develop/getting_started/concepts.html#what-is-a-variant>`_ directory, SPL Core will automatically use it to override the default configuration values defined in the ``KConfig`` file.
+The :ref:`variant <what_is_a_variant>` specific configuration file is expected in the :ref:`variant <what_is_a_variant>` directory.
+If a ``config.txt`` file is present in the :ref:`variant <what_is_a_variant>` directory, SPL Core will automatically use it to override the default configuration values defined in the ``KConfig`` file.

docs/getting_started/index.rst

@@ -9,3 +9,4 @@
    generate_example_project
    start_new_component
    from_legacy_to_configurable_component
+   start_new_variant

docs/getting_started/start_new_component.rst

@@ -11,6 +11,8 @@ To support :ref:`component <what_is_a_component>` development, SPL Core provides
 `Sphinx <https://www.sphinx-doc.org/>`_ is used to generate the component report.
 See the project `conf.py` file for the configuration details.
 
+.. _how_to_component_detail_design:
+
 Detailed Design
 ***************
 
@@ -128,6 +130,7 @@ Here is a ``index.rst`` template for getting you started documenting a component
             STATE_Y --> STATE_OFF : Power State == OFF
     {% endif %}
 
+.. _how_to_component_test_cases:
 
 Test Cases
 **********

docs/getting_started/start_new_variant.rst

@@ -0,0 +1,4 @@
+How to Start Working on a :ref:`Variant <what_is_a_variant>`
+############################################################
+
+TODO: write this section

docs/index.rst

@@ -5,6 +5,7 @@ Software Product Line (SPL) Core Documentation
     :maxdepth: 2
 
     getting_started/index
+    features/index
     reference/index
     internals/index
-    changelog/index
+    about/index

docs/internals/index.rst

@@ -71,19 +71,19 @@ Build kit *test*
    Build kit 'test' shall provide a build target 'unittests', that executes all tests of all SW components.
 
 .. req:: Support Creation of Documentation
-   :status: open
+   :status: done
 
    Build kit 'test' shall provide a build target '<component>_docs', that creates documentation of a SW component.
    Precondition of this build target is the existence of a doc folder inside the component's folder containing at
    least a conf.py.
 
 .. req:: Support Documentation
-   :status: open
+   :status: done
 
    Build kit 'test' shall provide a build target 'docs', that creates the documentation of all SW components.
 
 .. req:: Support Creation of a Component Report
-   :status: open
+   :status: done
 
    Build kit 'test' shall provide a build target '<component>_report', that creates a report of a SW component containing
    the documentation, test specification and all test results.
@@ -96,13 +96,13 @@ Build kit *test*
    SPL Core shall always start the docs target for generating the documentation and let sphinx-build handle the dependencies.
 
 .. req:: Configurable Sphinx Output
-   :status: open
+   :status: done
 
    The documentation shall be configurable. One should be able to generate the variant specific documentation, i.e.,
    only the variant specific components and their features shall be part of the documentation.
 
 .. req:: Project Documentation
-   :status: open
+   :status: done
 
    The project's index.rst file shall be static but changeable and configurable.
 
@@ -220,3 +220,19 @@ Component Reports CMake Target
 * we need to copy Doxyfile from the docs folder and then we have to update the paths where Doxyfile should find the sources
 * we need to call sphinx-build "pipenv run sphinx-build -b html . build/<Variant>/test/src/<Component>/reports/html"
     * source directory is always a projet root directory and output directory is build/<Variant>/test/src/<Component>/reports/
+
+
+Variant ``docs`` CMake Target
+-----------------------------
+
+Variant documentation will be created by the ``docs`` CMake target.
+This runs a sphinx-build using the project root index.rst file as input.
+Only the files included in the ``doc`` folder and inside each component's ``doc`` folder are part of the overall documentation. Therefore, there will be no traceability to IDs from ``src`` or ``test``.
+
+
+Variant ``reports`` CMake Target
+--------------------------------
+
+Variant reports will be created by the ``reports`` CMake target.
+This runs a sphinx-build using the project root index.rst file as input.
+In addition to the variant documentation, the variant report includes the component reports which include not only the docs but also the test results and the test specification.

docs/reference/index.rst

@@ -1,8 +1,9 @@
-🔧 Reference
+🛠️ Reference
 ************
 
 .. toctree::
     :maxdepth: 2
 
     macros
     variables
+    targets

docs/reference/targets.rst

@@ -0,0 +1,31 @@
+CMake Targets
+=============
+
+
+reports
+-------
+
+Generates the overall variant report.
+
+docs
+----
+
+Generates the variant documentation.
+
+.. _component_cmake_targets:
+
+<component>_report
+------------------
+
+Generate component report with full traceability between documentation, code and tests.
+
+<component>_docs
+----------------
+
+Generates the documentation for the given component.
+
+<component>_unittests
+---------------------
+
+Runs the unit tests for the given component.
+

src/common/cmake.py

@@ -26,8 +26,7 @@ def configure(self, variant: Variant, build_kit: str = "prod"):
             f" -B{self.workspace_artifacts.get_build_dir(variant, build_kit)}"
             f" -G Ninja "
             f" -DBUILD_KIT:STRING={build_kit}"
-            f" -DFLAVOR:STRING={variant.flavor}"
-            f" -DSUBSYSTEM:STRING={variant.subsystem}"
+            f" -DVARIANT:STRING={variant.to_string()}"
             f" -DCMAKE_BUILD_TYPE:STRING={variant.to_string('_')}"
         )
         if build_kit == "test":

src/project_creator/templates/project/{{cookiecutter.name}}/.gitignore

@@ -17,6 +17,9 @@ __pycache__/
 # Any backup file of text editors
 *.bak
 
+# Any log file
+*.log
+
 # Backup files of KConfig
 *.old
 
@@ -25,3 +28,6 @@ __pycache__/
 
 # bootstrap files are downloaded during installation
 /.bootstrap
+
+# Drawio Backup Files
+*.drawio.bkp

src/project_creator/templates/project/{{cookiecutter.name}}/.vscode/extensions.json

@@ -12,6 +12,7 @@
             "ms-python.vscode-pylance",
             "ms-python.python",
             "donjayamanne.python-environment-manager",
-            "felipecaputo.git-project-manager"
+            "felipecaputo.git-project-manager",
+            "ms-vscode.powershell"
         ]
 }

src/project_creator/templates/project/{{cookiecutter.name}}/.vscode/launch.json

@@ -30,9 +30,7 @@
                 "debug-test"
             ],
             "console": "integratedTerminal",
-            "env": {
-                "PYTEST_ADDOPTS": "--no-cov"
-            },
+            "env": {},
             "justMyCode": false
         }
     ]