docs: describe spl features and cmake targets

avengineers · Jan 9, 2024 · 0da12f4 · 0da12f4
1 parent 1cae615
commit 0da12f4
Show file tree

Hide file tree

Showing 10 changed files with 80 additions and 14 deletions.
diff --git a/.vscode/tasks.json b/.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"

diff --git a/docs/changelog/index.rst → docs/about/index.rst b/docs/changelog/index.rst → docs/about/index.rst
@@ -1 +1,4 @@
+📄 About
+********
+
 .. mdinclude:: ../../CHANGELOG.md
diff --git a/docs/features/index.rst b/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
diff --git a/docs/getting_started/concepts.rst b/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.
diff --git a/docs/getting_started/index.rst b/docs/getting_started/index.rst
@@ -9,3 +9,4 @@
    generate_example_project
    start_new_component
    from_legacy_to_configurable_component
+   start_new_variant
diff --git a/docs/getting_started/start_new_component.rst b/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
 **********

diff --git a/docs/getting_started/start_new_variant.rst b/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
diff --git a/docs/index.rst b/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
diff --git a/docs/reference/index.rst b/docs/reference/index.rst
@@ -1,8 +1,9 @@
-🔧 Reference
+🛠️ Reference
 ************
 
 .. toctree::
     :maxdepth: 2
 
     macros
     variables
+    targets
diff --git a/docs/reference/targets.rst b/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.
+