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

docs: restructuring, doxygen style docs: doxygen font docs: fixed typos docs: Add C++ section to structure API overview docs: Changelog docs: Improved docs on LinUnknownDatalength and Connection guides docs: Set sidebar navigation depth to 5 docs: Update changelog docs: Update changelog
vectorgrp · Oct 15, 2024 · 4c01ca2 · 4c01ca2
1 parent d53df04
commit 4c01ca2
Show file tree

Hide file tree

Showing 83 changed files with 1,835 additions and 1,507 deletions.
diff --git a/Demos/Lin/CMakeLists.txt b/Demos/Lin/CMakeLists.txt
@@ -30,3 +30,4 @@ target_sources(SilKitDemoLinDynamic
     PRIVATE DemoLin.silkit.yaml
     PRIVATE NetworkSimulatorConfig.yaml
 )
+
diff --git a/Demos/Lin/LinDemo.cpp b/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)
                     {

diff --git a/SilKit/include/silkit/capi/Lin.h b/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

diff --git a/SilKit/include/silkit/services/lin/LinDatatypes.hpp b/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

diff --git a/docs/CMakeLists.txt b/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)
diff --git a/docs/_static/custom.css b/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
+}
diff --git a/docs/api/api.rst b/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
diff --git a/docs/api/capi-can.rst → docs/api/capi/capi-can.rst b/docs/api/capi-can.rst → docs/api/capi/capi-can.rst
@@ -1,3 +1,5 @@
+.. include:: /substitutions.rst
+
 CAN C API
 ----------
 

diff --git a/docs/api/capi-data.rst → docs/api/capi/capi-data.rst b/docs/api/capi-data.rst → docs/api/capi/capi-data.rst
@@ -1,3 +1,5 @@
+.. include:: /substitutions.rst
+
 Data Publish/Subscribe C API
 ----------------------------
 

diff --git a/docs/api/capi-ethernet.rst → docs/api/capi/capi-ethernet.rst b/docs/api/capi-ethernet.rst → docs/api/capi/capi-ethernet.rst
@@ -1,3 +1,5 @@
+.. include:: /substitutions.rst
+
 Ethernet C API
 --------------
 

diff --git a/docs/api/capi-flexray.rst → docs/api/capi/capi-flexray.rst b/docs/api/capi-flexray.rst → docs/api/capi/capi-flexray.rst
@@ -1,3 +1,5 @@
+.. include:: /substitutions.rst
+
 FlexRay C API
 -------------
 

diff --git a/docs/api/capi-lin.rst → docs/api/capi/capi-lin.rst b/docs/api/capi-lin.rst → docs/api/capi/capi-lin.rst
@@ -1,3 +1,5 @@
+.. include:: /substitutions.rst
+
 LIN C API
 ---------
 
@@ -81,6 +83,7 @@ Enumerations and Typedefs
 .. doxygentypedef:: SilKit_LinFrameResponseType
 .. doxygentypedef:: SilKit_LinFrameStatus
 .. doxygentypedef:: SilKit_LinDataLength
+.. doxygenvariable:: SilKit_LinDataLengthUnknown
 
 .. doxygentypedef:: SilKit_LinFrameStatusHandler_t
 .. doxygentypedef:: SilKit_LinGoToSleepHandler_t

diff --git a/docs/api/capi-main.rst → docs/api/capi/capi-main.rst b/docs/api/capi-main.rst → docs/api/capi/capi-main.rst
@@ -1,3 +1,5 @@
+.. include:: /substitutions.rst
+
 .. _sec:capi:
 
 ================================

diff --git a/docs/api/capi-orchestration.rst → docs/api/capi/capi-orchestration.rst b/docs/api/capi-orchestration.rst → docs/api/capi/capi-orchestration.rst
@@ -1,3 +1,5 @@
+.. include:: /substitutions.rst
+
 Orchestration C API
 ----------------------------
 

diff --git a/docs/api/capi-rpc.rst → docs/api/capi/capi-rpc.rst b/docs/api/capi-rpc.rst → docs/api/capi/capi-rpc.rst
@@ -1,3 +1,5 @@
+.. include:: /substitutions.rst
+
 RPC C API
 -----------
 

diff --git a/docs/api/capi-systemmonitor.rst → docs/api/capi/capi-systemmonitor.rst b/docs/api/capi-systemmonitor.rst → docs/api/capi/capi-systemmonitor.rst
@@ -1,3 +1,5 @@
+.. include:: /substitutions.rst
+
 System Monitor C API
 ---------------------
Original file line number	Diff line number	Diff line change
Expand Up		@@ -30,3 +30,4 @@ target_sources(SilKitDemoLinDynamic
		PRIVATE DemoLin.silkit.yaml
		PRIVATE NetworkSimulatorConfig.yaml
		)