SILKIT-1392: Configuration docs (#698)

* SILKIT-1392: Includes config

* SILKIT-1392: Added ParticipantConfigFromFile/String API reference and mention usage in Includes section.

docs/CHANGELOG.rst

@@ -18,10 +18,17 @@ Fixed
 [4.0.38] - 2023-09-19
 ---------------------
 
+Changed
+~~~~~~~
+
+- Reworked the documentation on Participant Configuration
+
 Added
 ~~~~~
 
 - Reintroduced build requirements to documentation
+- Documentation for Includes section in Participant Configuration
+
 
 [4.0.37] - 2023-10-17
 ---------------------
@@ -4788,7 +4795,7 @@ Removed
     - removed FastRtps specific integration tests.
     - API: removed deprecated `ib::CreateFastRtpsComAdapter` and `ib::CreateVAsioComAdapter`.
       Users should use the generic :cpp:func:`CreateComAdapter<ib::CreateComAdapter()>`,
-      refer to :ref:`changelog-outdated-reference` (``sec:mwcfg-vasio``).
+      refer to :ref:`changelog-outdated-reference`.
     - ConfigBuilder: removed FastRtps configuration mechanism: `ib::cfg::ConfigBuilder::ConfigureFastRtps`.
 
 
@@ -5048,10 +5055,10 @@ the removal of ``ComAdapter::SendIbMessage`` methods.
 Changed
 ~~~~~~~
 
-.. admonition:: Note: the FastRTPS middleware is now deprecated
-
-   See :ref:`sec:mwcfg` for migration instructions.
+.. admonition:: Note:
 
+   The FastRTPS middleware is now deprecated
+
 - The middleware `FastRTPS` is now marked as deprecated.
   This middleware will be removed in the future.
   The middleware specific `CreateFastRtpsComAdapter` API has been

docs/api/logging.rst

@@ -1,27 +1,27 @@
-===================
-Logging Service API
-===================
-
-SIL Kit provides a Logging service that can be used for writing log messages of specified log levels to files, stdout 
-or distribute them with remote logging to other simulation participants. The logger can be obtained by calling 
-:cpp:func:`GetLogger()<SilKit::IParticipant::GetLogger>`. Refer to :ref:`Logging Configuration<sec:cfg-logging-configuration-overview>` for 
-how to configure the logging service.
-
-.. contents::
-   :local:
-   :depth: 2
-
-.. _sec:logging-api:
-
-API
----
-
-.. doxygenclass:: SilKit::Services::Logging::ILogger
-   :members:
-
-.. _sec:logging-data-types:
-
-Data Type Reference
--------------------
-
-.. doxygenenum:: SilKit::Services::Logging::Level
+===================
+Logging Service API
+===================
+
+SIL Kit provides a Logging service that can be used for writing log messages of specified log levels to files, stdout 
+or distribute them with remote logging to other simulation participants. The logger can be obtained by calling 
+:cpp:func:`GetLogger()<SilKit::IParticipant::GetLogger>`. Refer to :ref:`Logging Configuration<sec:cfg-participant-logging>` for 
+how to configure the logging service.
+
+.. contents::
+   :local:
+   :depth: 2
+
+.. _sec:logging-api:
+
+API
+---
+
+.. doxygenclass:: SilKit::Services::Logging::ILogger
+   :members:
+
+.. _sec:logging-data-types:
+
+Data Type Reference
+-------------------
+
+.. doxygenenum:: SilKit::Services::Logging::Level

docs/configuration/configuration.rst

@@ -2,90 +2,96 @@
 Configuration
 ========================================
 
+.. |ProductName| replace:: SIL Kit
+
 .. _sec:sil-kit-config-yaml:
 
-The Vector SIL Kit provides optional configuration to enhance flexibility and control through use of YAML files.
+The Vector |ProductName| provides optional configuration to enhance flexibility and control through use of YAML files.
 This allows users to modify behavior without recompiling source code.
 Further, it allows configuration of services which are inactive by default, such as tracing and logging.
+Different configuration options are available for |ProductName| participants and the |ProductName| Registry.
 
 .. contents::
    :local:
-   :depth: 2
+   :depth: 1
 
 .. _sec:participant-config:
 
 The Participant Configuration File
 =======================================
 
-Vector SIL Kit simulation participants are primarily configured by developers in source code using the SIL Kit API.
+Participants are primarily configured by developers in source code using the |ProductName| API.
 However, the following scenarios are conceivable in which some flexibility is useful even after compile-time:
 
-- A simulation participant is distributed in binary form to integrators. In order to integrate such 
-  participants into simulations, an integrator must be able to post-configure some aspects of the participant to make it fit,
-  particularly its properties, behavior and how it interconnects within a simulation.
-- A simulation consists of multiple participants that share the same behavior. An integrator would have to ask developers to compile 
-  these participants from the same sources multiple times, with only the participant names differing.
-- Developers or integrators want to temporarily enable debugging features without the need or the ability to recompile the sources, 
-  for example logging, tracing, and health checking.
-
-To cover these scenarios, Vector SIL Kit offers the ability to modify a participant's configuration via participant configuration files,
-often simply referred to as *participant configuration*. The feature can be enabled by passing the file as an argument when a participant 
-is created, :cpp:func:`CreateParticipant(std::shared_ptr\<SilKit::Config::IParticipantConfiguration\> participantConfig, ...)<SilKit::CreateParticipant()>`.
-
-Participant configuration files allow to override a subset of parameters which are configurable via the SIL Kit API.
-Configuration parameters that are specified within the participant configuration override corresponding 
-programmatically defined values. For example, the ``ParticipantName`` field of the participant configuration overrides the 
-participant name that is provided through the API of the Vector SIL Kit when participants are created, namely 
-:cpp:func:`CreateParticipant(..., const std::string& participantName, ...)<SilKit::CreateParticipant()>`. This gives integrators the ability to run
-a simulation with multiple instances of a participant from a single implementation.
+- A simulation participant is distributed in binary form to integrators. 
+  In order to integrate such participants into simulations, an integrator must be able to post-configure some aspects of the participant to make it fit, particularly its properties, behavior and how it interconnects within a simulation.
+- A simulation consists of multiple participants that share the same behavior. 
+  An integrator would have to ask developers to compile these participants from the same sources multiple times, with only the participant names differing.
+- Developers or integrators want to temporarily enable debugging features without the need or the ability to recompile the sources, for example logging, tracing, and health checking.
 
-.. admonition:: Note
+To cover these scenarios, |ProductName| participants can be modified by *participant configuration files*. 
+This is done by creating a participant configuration object from a given file and passing the object as an argument when a participant is created:
+
+.. code-block:: c++
 
-    It is recommended that all configuration be done at the source code level so that an empty configuration file can be provided for most simulation runs.
-    A user should be able to create (or modify an existing) configuration file for a participant, if behavior or network connections need to be reconfigured.
+  auto participantConfiguration = SilKit::Config::ParticipantConfigurationFromFile(participantConfigurationFilename);
+  auto participant = SilKit::CreateParticipant(participantConfiguration, participantName, registryUri);
+
+Participant configuration files allow to override a subset of parameters which are configurable via the |ProductName| API.
+Configuration parameters that are specified within the participant configuration override corresponding programmatically defined values. 
+For example, the ``ParticipantName`` field overrides the participant name that is provided through the API when a participant is created, namely :cpp:func:`CreateParticipant(..., const std::string& participantName, ...)<SilKit::CreateParticipant()>`. 
+This gives integrators the ability to run a simulation with multiple instances of a participant from a single implementation.
+
+.. admonition:: Note
 
-A participant configuration file is written in YAML syntax according to a specified schema. It begins with some general information 
-about the configuration file itself, followed by several subsections for the different services of the Vector SIL Kit.
+    It is recommended that configurations are specified in the source code where possible.
+    That way, an empty configuration file can be provided for most simulation runs.
+    However, a process that creates a |ProductName| participant should also accept a configuration file
+    such that a user is able to reconfigure names or network connections without recompiling the application.
 
 .. admonition:: Note
 
     Many IDEs automatically support participant configuration schema support when the participant configuration file ends with the suffix ``.silkit.json/yaml``.
 
+A participant configuration file is written in YAML syntax according to a specified schema. 
+It starts with the ``SchemaVersion``, the ``Description`` for the configuration and the ``ParticipantName``. 
+This is followed by further sections for ``Includes``, ``Middleware``, ``Logging``, ``HealthCheck``, ``Tracing``, ``Extentions`` and sections for the different services of the |ProductName|.
 The outline of a participant configuration file is as follows:
 
 .. code-block:: yaml
                 
-    ---
     "$schema": "./ParticipantConfiguration.schema.json"
-    schemaVersion: 1
-    Description: Sample configuration with all major subsections
+    SchemaVersion: 1
+    Description: Sample configuration with all root nodes
     ParticipantName: Participant1
+    Middleware: 
+      ...
+    Logging: 
+      ...
+    HealthCheck: 
+      ...
+    Tracing:
+      ...
+    Extensions: 
+      ...
+    Includes: 
+      - ...
     CanControllers:
-    - ...
+      - ...
     LinControllers: 
-    - ...
+      - ...
     FlexrayControllers: 
-    - ...
+      - ...
     EthernetControllers: 
-    - ...
+      - ...
     DataPublishers: 
-    - ...
+      - ...
     DataSubscribers: 
-    - ...
+      - ...
     RpcClients: 
-    - ...
+      - ...
     RpcServers: 
-    - ...
-    Logging: 
-    - ...
-    HealthCheck: 
-    - ...
-    Tracing:
-      ...
-    Extensions: 
-    - ...
-    Middleware: 
-    - ...
+      - ...
 
 .. _subsec:participant-config-overview:
 
@@ -100,26 +106,21 @@ Overview
      - Description
 
    * - $schema
-     - The location of the participant configuration schema file. The ``ParticipantConfiguration.schema.json`` is
-       part of the SIL Kit sources and can be found in the folder
-       ``./SilKit/source/config/``.
+     - File path to the participant configuration schema. 
+       The ``ParticipantConfiguration.schema.json`` is part of the |ProductName| sources and can be found in the folder ``./SilKit/source/config/``.
 
    * - schemaVersion
      - The version of the used participant configuration schema. Current version is 1.
-
-   * - ParticipantName
-     - The name of the simulation participant that joins the Vector SIL Kit simulation. Overrides a programmatically
-       defined participant name.
-
-   * - :doc:`CanControllers<configuration-services>`, 
-       :doc:`LinControllers<configuration-services>`,
-       :doc:`FlexrayControllers<configuration-services>`,
-       :doc:`EthernetControllers<configuration-services>`,
-       :doc:`DataPublishers<configuration-services>`,
-       :doc:`DataSubscribers<configuration-services>`,
-       :doc:`RpcClients<configuration-services>`,
-       :doc:`RpcServers<configuration-services>`
-     - These sections are used to configure bus controllers and other communication services.
+
+   * - ``Description``
+     - User defined description for the configuration.
+
+   * - ``ParticipantName``
+     - The name of the simulation participant that joins the |ProductName| simulation. 
+       Overrides a programmatically defined participant name.
+
+   * - :ref:`Includes<sec:cfg-participant-includes>`
+     - This can be used to include other participant configuration files.
 
    * - :ref:`Logging<sec:cfg-participant-logging>`
      - The logger configuration for this participant.
@@ -130,25 +131,47 @@ Overview
    * - :ref:`Tracing<sec:cfg-participant-tracing>`
      - Configuration of experimental tracing and replay functionality.
 
-   * - :doc:`Extensions<extension-configuration>`
-     - Configuration of optional extensions to the Vector SIL Kit and where to find them.
+   * - :ref:`Extensions<sec:cfg-participant-extensions>`
+     - Configuration of optional extensions to the |ProductName| and where to find them.
 
-   * - :doc:`Middleware<middleware-configuration>`
-     - This optional section can be used to configure the middleware running the Vector SIL Kit.
+   * - :ref:`Middleware<sec:cfg-participant-middleware>`
+     - This optional section can be used to configure the middleware running the |ProductName|.
        If this section is omitted, defaults will be used.
 
-.. _subsec:participant-config-options:
+   * - :ref:`CanControllers<sec:cfg-participant-can>`
+     - Configure CAN controllers.
+
+   * - :ref:`LinControllers<sec:cfg-participant-lin>`
+     - Configure LIN controllers.
+
+   * - :ref:`EthernetControllers<sec:cfg-participant-ethernet>`
+     - Configure Ethernet controllers.
+
+   * - :ref:`FlexrayControllers<sec:cfg-participant-flexray>`
+     - Configure Flexray controllers.
+
+   * - :ref:`DataPublishers<sec:cfg-participant-data-publishers>`
+     - Configure data publishers.
+
+   * - :ref:`DataSubscribers<sec:cfg-participant-data-subscribers>`
+     - Configure data subscribers.
+
+   * - :ref:`RpcServers<sec:cfg-participant-rpc-servers>`
+     - Configure RPC servers.
+
+   * - :ref:`RpcClients<sec:cfg-participant-rpc-clients>`
+     - Configure RPC clients.
 
 Configuration Options
 ~~~~~~~~~~~~~~~~~~~~~
-
 .. toctree::
-   :maxdepth: 2
+   :maxdepth: 1
 
-   configuration-services
+   services-configuration
+   includes-configuration
    logging-configuration
    healthcheck-configuration
-   configuration-tracing
+   tracing-configuration
    extension-configuration
    middleware-configuration
 
@@ -157,12 +180,9 @@ Configuration Options
 The Registry Configuration File
 ===============================
 
-An instance of the SIL Kit Registry (``sil-kit-registry(.exe)``) can be
-configured via a YAML file.
-The configuration file is optional and overrides the settings specified on the
-command line.
-It also allows extended configuration, beyond what the command line allows,
-particularly for logging.
+An instance of the |ProductName| Registry (``sil-kit-registry(.exe)``) can be configured via a YAML file.
+The configuration file is optional and overrides the settings specified on the command line.
+It also allows extended configuration, beyond what the command line allows, particularly for logging.
 
 The outline of a registry configuration file is as follows:
 
@@ -224,7 +244,7 @@ Overview
        This field overrides the ``-d``, and ``--dashboard-uri`` command line
        parameters.
 
-       **NOTE** The default URI to use for a local SIL Kit dashboard setup is http://localhost:8082.
+       **NOTE** The default URI to use for a local |ProductName| dashboard setup is http://localhost:8082.
 
 .. _subsec:registry-config-options:
 
@@ -235,3 +255,12 @@ Configuration Options
    :maxdepth: 2
 
    logging-configuration
+
+
+API and Data Type Reference
+---------------------------
+
+.. doxygenfunction:: SilKit::Config::ParticipantConfigurationFromFile
+
+.. doxygenfunction:: SilKit::Config::ParticipantConfigurationFromString
+