diff --git a/.vscode/tasks.json b/.vscode/tasks.json index 9ce77c8..d7fa270 100644 --- 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 b/docs/about/index.rst similarity index 57% rename from docs/changelog/index.rst rename to docs/about/index.rst index 6ae006a..ad3ef0a 100644 --- a/docs/changelog/index.rst +++ b/docs/about/index.rst @@ -1 +1,4 @@ +📄 About +******** + .. mdinclude:: ../../CHANGELOG.md diff --git a/docs/features/index.rst b/docs/features/index.rst new file mode 100644 index 0000000..0e5e038 --- /dev/null +++ b/docs/features/index.rst @@ -0,0 +1,12 @@ +✨ Features +************ + +Variant Report +-------------- + +... + +Component Report +---------------- + +... \ No newline at end of file diff --git a/docs/getting_started/concepts.rst b/docs/getting_started/concepts.rst index c0cbaf3..00fd9d6 100644 --- 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 `_, which are used to develop several versions of a computer program, also known as `variants `_. +An SPL is a software project that contains shared and configurable source code elements known as :ref:`components `, which are used to develop several versions of a computer program, also known as :ref:`variants `. 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 `_ 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 `_ we need. +But they all start from some common :ref:`components ` 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 ` we need. What is SPL Core? ----------------- SPL Core is a tool chain that uses modern `CMake `_. -SPL Core supports the concepts and requirements of an SPL to build various software `variants `_ from a common codebase. +SPL Core supports the concepts and requirements of an SPL to build various software :ref:`variants ` 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 `_ that meet specific customer requirements. +A variant is a specific version of the software, consisting of a set of :ref:`features ` that meet specific customer requirements. -Think of a variant like choosing different `features `_ for your car. +Think of a variant like choosing different :ref:`features ` 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 `_ that are part of the variant. -* ``config.txt`` - this is the `feature `_ selection of the variant. It is a KConfig file that contains the selected `features `_ of the variant. +* ``parts.cmake`` - contains the list of :ref:`components ` that are part of the variant. +* ``config.txt`` - this is the :ref:`feature ` selection of the variant. It is a KConfig file that contains the selected :ref:`features ` 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 `. +.. _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 `_, ensuring that feature combinations are viable and consistent. +This model guides the creation of different SPL :ref:`variants `, 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 `_ specific configuration file is expected in the `variant `_ directory. -If a ``config.txt`` file is present in the `variant `_ directory, SPL Core will automatically use it to override the default configuration values defined in the ``KConfig`` file. +The :ref:`variant ` specific configuration file is expected in the :ref:`variant ` directory. +If a ``config.txt`` file is present in the :ref:`variant ` directory, SPL Core will automatically use it to override the default configuration values defined in the ``KConfig`` file. diff --git a/docs/index.rst b/docs/index.rst index 8f085d3..29877c9 100644 --- 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 \ No newline at end of file + about/index diff --git a/docs/reference/index.rst b/docs/reference/index.rst index f916b14..7b1a539 100644 --- a/docs/reference/index.rst +++ b/docs/reference/index.rst @@ -1,4 +1,4 @@ -🔧 Reference +🛠️ Reference ************ .. toctree:: @@ -6,3 +6,4 @@ macros variables + targets diff --git a/docs/reference/targets.rst b/docs/reference/targets.rst new file mode 100644 index 0000000..2ce2163 --- /dev/null +++ b/docs/reference/targets.rst @@ -0,0 +1,29 @@ +CMake Targets +============= + + +reports +------- + +Generates the overall variant report. See `Variant Report` for more information. + +docs +---- + +Generates the variant documentation. + +_report +------------------ + +Generates the report for the given component. See `Component Report` for more information. + +_docs +---------------- + +Generates the documentation for the given component. + +_unittests +--------------------- + +Runs the unit tests for the given component. +