docs: Improve demo and troubleshooting sections (#127)

* docs: Improved docs (Demos, Throubleshooting, CSS, file structure)

Demos/Lin/CMakeLists.txt

@@ -30,3 +30,4 @@ target_sources(SilKitDemoLinDynamic
     PRIVATE DemoLin.silkit.yaml
     PRIVATE NetworkSimulatorConfig.yaml
 )
+

Demos/Lin/LinDemo.cpp

@@ -506,7 +506,7 @@ try
                     {
                         master.DoAction(now);
                         now += 1ms;
-                        std::this_thread::sleep_for(200ms);
+                        std::this_thread::sleep_for(100ms);
                     }
                     if (!isStopRequested)
                     {
@@ -587,7 +587,7 @@ try
                     {
                         slave.DoAction(now);
                         now += 1ms;
-                        std::this_thread::sleep_for(200ms);
+                        std::this_thread::sleep_for(100ms);
                     }
                     if (!isStopRequested)
                     {

SilKit/include/silkit/capi/Lin.h

@@ -160,7 +160,7 @@ typedef uint8_t SilKit_LinFrameStatus;
  */
 typedef uint8_t SilKit_LinDataLength;
 
-//! \brief If configured with this value, the data length of the first reception will be used.
+//! \brief If configured for reception with this value, the data length validation of incoming frames is skipped.
 const SilKit_LinDataLength SilKit_LinDataLengthUnknown = 255u;
 
 /*! \brief A LIN SilKit_LinFrame

SilKit/include/silkit/services/lin/LinDatatypes.hpp

@@ -68,7 +68,7 @@ enum class LinChecksumModel : SilKit_LinChecksumModel
  */
 using LinDataLength = SilKit_LinDataLength;
 
-//! \brief If configured with this value, the data length of the first reception will be used.
+//! \brief If configured for reception with this value, the data length validation of incoming frames is skipped.
 const LinDataLength LinDataLengthUnknown = SilKit_LinDataLengthUnknown;
 
 /*! \brief A LIN LinFrame

docs/CHANGELOG.rst

@@ -9,6 +9,10 @@ The format is based on `Keep a Changelog (http://keepachangelog.com/en/1.0.0/) <
 [4.0.54] - Unreleased
 ---------------------
 
+Changed
+~~~~~~~
+
+- Revised the documentation (demos, troubleshooting, doxygen output, file structure)
 
 [4.0.53] - 2024-10-11
 ---------------------
@@ -1608,7 +1612,7 @@ Changed
   The command line tools were updated to accept a new parameter for this.
 - The command line tools were modified to use lower case names with dashes:
   E.g., the ``IbRegistry`` is now called ``sil-kit-registry``.
-  See  :doc:`./usage/utilities`  for details.
+  See  :doc:`./utilities/utilities`  for details.
 
 - The trivial simulation and the detailed simulation have been made more consistent:
 
@@ -3997,7 +4001,7 @@ Removed
 Changed
 ~~~~~~~
 
-- Updated documentation of :doc:`./usage/demos`, :doc:`./usage/utilities` and :doc:`./configuration/configuration`
+- Updated documentation of :doc:`./demos/demos`, :doc:`./utilities/utilities` and :doc:`./configuration/configuration`
 
 
 - Participant (formerly 'ComAdapter') methods to create DataPublisher, DataSubscriber, RpcClient and RpcServer now have an additional 
@@ -6392,17 +6396,17 @@ This is a Quality Assured Release.
 
 Added
 ~~~~~
-- Documentation for the CAN controller API: :doc:`CAN Vehicle Network Controllers <api/can>`.
+- Documentation for the CAN controller API: :doc:`CAN Vehicle Network Controllers <api/services/can>`.
 - Documentation for the Participant Controller API: :ref:`changelog-outdated-reference` (``api/participantcontroller``) (AFTMAGT-206).
 - Documentation for the IO Port services (AFTMAGT-201).
 - Documented Generic Messages API: (AFTMAGT-204).
 - Documented the simulation state machine and synchronization types: :doc:`simulation/simulation`
 - Added docs for the ComAdapter:
 - Added quick start guide: usage/quickstart
 - Elaborate the user APIs and overview pages: :doc:`api/api`
-- Add docs for :doc:`api/systemcontroller` (AFTMAGT-242).
-- Add docs for :doc:`api/systemmonitor` (AFTMAGT-242).
-- Add docs for :doc:`api/ethernet` (AFTMAGT-239).
+- Add docs for :doc:`api/system-utilities/systemcontroller` (AFTMAGT-242).
+- Add docs for :doc:`api/system-utilities/systemmonitor` (AFTMAGT-242).
+- Add docs for :doc:`api/services/ethernet` (AFTMAGT-239).
 
 Changed
 ~~~~~~~
@@ -6686,7 +6690,7 @@ Changed
 - The LIN API was redesigned to provide a clearer and simpler interface. To make
   the transition to the new API as simple as possible, we provided extensive
   documentation on the new API itself including usage examples and information
-  about what changed in the new API: :doc:`../api/lin`
+  about what changed in the new API: :doc:`../api/services/lin`
 - Removed spdlog from the public IB API. Spdlog is still used internally but it
   has been removed from the public API to avoid conflicts with user specific
   spdlog installations.

docs/CMakeLists.txt

@@ -43,6 +43,7 @@ endif()
 #Replace variables inside @@ with the current values
 configure_file(${DOXYFILE_IN} ${DOXYFILE_OUT} @ONLY)
 
+
 #Doxygen won't create this for us
 file(MAKE_DIRECTORY ${DOXYGEN_OUTPUT_DIR})
 
@@ -56,6 +57,7 @@ set(SPHINX_INDEX_FILE ${SPHINX_BUILD}/index.html)
 # - The Sphinx config has been updated
 file(GLOB_RECURSE SPHINX_SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.rst)
 file(GLOB_RECURSE SVG_FILES ${CMAKE_CURRENT_SOURCE_DIR}/*.svg)
+list(APPEND SPHINX_SOURCE_FILES ${CMAKE_CURRENT_SOURCE_DIR}/_static/custom.css)
 
 if (UNIX)
   if (${SILKIT_WARNINGS_AS_ERRORS})
@@ -106,5 +108,5 @@ install(
     COMPONENT docs
     )
 #add sample code so it shows in the IDE, but don't build or install it
-add_executable(sample_silkit_new_config EXCLUDE_FROM_ALL usage/sample_silkit/simple.cpp)
+add_executable(sample_silkit_new_config EXCLUDE_FROM_ALL code-samples/simple/simple.cpp)
 target_link_libraries(sample_silkit_new_config PRIVATE SilKit)

docs/_static/custom.css

@@ -13,6 +13,7 @@
     max-width: 1240px;
 }
 
+/* custom styling for literals: center properly and change color */
 .rst-content code.literal {
 	position: relative;
 	top: -0.08rem;
@@ -21,10 +22,53 @@
 	background: none;
 }
 
+/* custom styling for literals + links: center properly and change color */
 .rst-content code.xref {
 	position: relative;
 	top: -0.08rem;
 	color: #062873;
 	font-weight: 700;
 	background: none;
 }
+
+/* custom doxygenfunction style */
+
+:root {
+	--doxygen-font-family: Lato, proxima-nova, Helvetica Neue, Arial, sans-serif;
+	--codeblock-font-family: SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,Courier,monospace;
+}
+
+/* Font, size, weight for the function signature */
+.cpp dt.sig.sig-object.cpp {
+	font-family: var(--doxygen-font-family) !important;
+	font-size: 14px !important;
+	font-weight: 400;
+}
+
+/* Color for function namespace in function signature */
+/*.cpp dt.sig.sig-object.cpp span.sig-prename.descclassname {
+	color: #00008B
+}*/
+
+/* Color for function name in function signature */
+.cpp dt.sig.sig-object.cpp span.sig-name.descname {
+	color: #00008B !important;
+	font-weight: 700;
+}
+
+/* Color for function parameters in function signature */
+.cpp dt.sig.sig-object.cpp span.n.sig-param {
+	color: #00008B
+}
+
+/* Font and color for function parameters in list */
+.cpp.function strong {
+	font-family: var(--doxygen-font-family);
+	color: #0047AB
+}
+
+/* Font and color for exceptions in list */
+.cpp.function .cpp-expr.sig.sig-inline.cpp {
+	font-family: var(--doxygen-font-family);
+	color: #E97451
+}

docs/api/api.rst

@@ -1,132 +1,161 @@
-===
-API
-===
-.. |Participant| replace:: :doc:`Participant<participant>`
-.. |header| replace:: :doc:`header<header>`
+.. include:: /substitutions.rst
 
+=========
+C/C++ API
+=========
 
-This document describes the user available programming interfaces of the Vector
-SIL Kit (SIL Kit). If you are not yet familiar with the SIL Kit, have a look at
-the :doc:`Developers Guide<../for-developers/developers>`.
+This document describes the user available programming interfaces of the Vector |ProductName|.
+If you are not yet familiar with the |ProductName|, have a look at the :doc:`Developers Guide<../for-developers/developers>`.
+Information on API organization in the |ProductName|:
 
+.. toctree::
+   :maxdepth: 1
+
+   header
+   memory-management
+
+C++ API
+-------
 
-API Entry Point and API Organization
-------------------------------------
+Participant
+~~~~~~~~~~~
 
-The Participant constitutes the main entry point into the SIL Kit API.
+The Participant constitutes the main entry point into the |ProductName| API.
 
 .. toctree::
    :maxdepth: 1
 
    participant
-   header
-   memory-management
-
+
 .. _sec:api-services:
 
 Services
---------
+~~~~~~~~
 
 The services API includes common data types, supports various vehicular networks, and provides generic publish/subscribe and RPC facilities.
 
+Logging
++++++++
+
+The Logging service can be used for writing log messages of specified log levels to various types of sinks.
+
 .. toctree::
    :maxdepth: 1
-   
-   logging
+
+   services/logging
 
 Vehicle Network Controller
-~~~~~~~~~~~~~~~~~~~~~~~~~~
-Several different vehicular networks are supported by corresponding
-controller interfaces.
+++++++++++++++++++++++++++
+
+Several different vehicular networks are supported by corresponding controller interfaces.
 
 .. toctree::
   :maxdepth: 1
 
-  can
-  lin
-  flexray
-  ethernet
+  services/can
+  services/lin
+  services/flexray
+  services/ethernet
 
 Data Publish/Subscribe and RPC
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++
 
-These services do not model a real-world bus and can be used for
-generic programming and interoperability tasks.
+These services do not model a real-world bus and can be used for generic programming and interoperability tasks.
 
 .. toctree::
   :maxdepth: 1
 
-  pubsub
-  rpc
+  services/pubsub
+  services/rpc
 
-SIL Kit provides a recommended default serialization/deserialization API for Data Publish/Subscribe and RPC:
+|ProductName| provides a recommended default serialization/deserialization API for Data Publish/Subscribe and RPC:
 
 .. toctree::
   :maxdepth: 1
 
   serdes
 
 State Handling and Synchronization
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+++++++++++++++++++++++++++++++++++
+
+The following services provide time synchronization and orchestrated state management.
+
+.. toctree::
+  :maxdepth: 1
+
+  services/lifecycle
+  services/timesync
+
 
-The following services provide time synchronization and orchestrated state
-management.
+System Utilities
+++++++++++++++++
+
+These system utilities can be used to control and monitor the simulation as a whole.
 
 .. toctree::
   :maxdepth: 1
 
-  lifecycleService
-  timeSyncService
-  systemcontroller
-  systemmonitor
+  system-utilities/systemcontroller
+  system-utilities/systemmonitor
 
 Common Data Types
-~~~~~~~~~~~~~~~~~
++++++++++++++++++
+
+Some data types are shared between services of the |ProductName|.
+
+.. toctree::
+  :maxdepth: 1
+
+  common-data-types
+
+Custom Network Simulator
+++++++++++++++++++++++++
 
 .. toctree::
   :maxdepth: 1
 
-  common
+  netsim
+
 
 C API
 -----
 
-The SIL Kit provides an additional API that allows to use the SIL Kit directly
+The |ProductName| provides an additional API that allows to use the |ProductName| directly
 with the C programming language:
 
 .. toctree::
   :maxdepth: 1
 
-  capi-main
+  capi/capi-main
 
 Services
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+~~~~~~~~
 
 Vehicle Network Controller
 ++++++++++++++++++++++++++
 
 .. toctree::
   :maxdepth: 1
 
-  capi-can
-  capi-ethernet
-  capi-lin
-  capi-flexray
+  capi/capi-can
+  capi/capi-ethernet
+  capi/capi-lin
+  capi/capi-flexray
 
 Data Publish/Subscribe and RPC
 ++++++++++++++++++++++++++++++
 
 .. toctree::
   :maxdepth: 1
 
-  capi-data
-  capi-rpc
+  capi/capi-data
+  capi/capi-rpc
 
 State Handling and Synchronization
 ++++++++++++++++++++++++++++++++++
 
 .. toctree::
   :maxdepth: 1
 
-  capi-orchestration
-  capi-systemmonitor
+  capi/capi-orchestration
+  capi/capi-systemmonitor