[21416] Enhance Fast DDS docs with a FAQs section covering every subsection

code/Examples/C++/DDSHelloWorld/src/HelloWorldCdrAux.ipp

@@ -113,8 +113,13 @@ void serialize_key(
         eprosima::fastcdr::Cdr& scdr,
         const HelloWorld& data)
 {
+
     static_cast<void>(scdr);
     static_cast<void>(data);
+                        scdr << data.index();
+
+                        scdr << data.message();
+
 }
 
 

docs/02-formalia/titlepage.rst

@@ -218,3 +218,6 @@ This documentation is organized into the sections below.
 * :ref:`Fast DDS <getting_started>`
 * :ref:`Fast DDS-Gen <fastddsgen_intro>`
 * :ref:`Release Notes <release_notes>`
+
+The documentation includes a :ref:`Frequently Asked Questions (FAQ) <frequently_asked_questions>` section that can be
+consulted for a quick overview.

docs/conf.py

@@ -47,8 +47,7 @@ def download_css(html_css_dir):
         False if not.
     """
     url = (
-        'https://raw.githubusercontent.com/eProsima/all-docs/'
-        'master/source/_static/css/fiware_readthedocs.css')
+        'https://raw.githubusercontent.com/eProsima/all-docs/master/source/_static/css/fiware_readthedocs.css')
     try:
         req = requests.get(url, allow_redirects=True, timeout=10)
     except requests.RequestException as e:
@@ -343,7 +342,8 @@ def configure_doxyfile(
     'breathe',
     'sphinxcontrib.plantuml',
     'sphinx.ext.autodoc',  # Document Pydoc documentation from Python bindings.
-    'sphinx_tabs.tabs'
+    'sphinx_tabs.tabs',
+    'sphinx_toolbox.collapse'
 ]
 
 sphinx_tabs_disable_css_loading = False
@@ -366,6 +366,7 @@ def configure_doxyfile(
 except ImportError:
     pass
 
+
 # Default behaviour for `autodoc`: always show documented members.
 autodoc_default_options = {
         'members': True,
@@ -461,7 +462,7 @@ def configure_doxyfile(
 
 suppress_warnings = [
     'cpp.duplicate_declaration',
-    'cpp.parse_function_declaration'
+    'cpp.parse_function_declaration',
 ]
 
 # Check if we are checking the spelling. In this case...
@@ -471,6 +472,7 @@ def configure_doxyfile(
     # Avoid the warning of a wrong reference in the TOC entries,
     # because fails the Python API Reference reference.
     suppress_warnings.append('toc.excluded')
+    suppress_warnings.append('config.cache')
 
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False

docs/fastdds/api_reference/rtps/participant/participantdiscoveryinfo/ParticipantDiscoveryStatus.rst

@@ -1,7 +1,7 @@
 .. rst-class:: api-ref
 
 ParticipantDiscoveryStatus
-----------------------------
+--------------------------
 
 .. doxygenenum:: eprosima::fastdds::rtps::ParticipantDiscoveryStatus
     :project: FastDDS

docs/fastdds/faq/discovery/discovery.rst

@@ -0,0 +1,131 @@
+.. include:: ../../../03-exports/aliases.include
+.. include:: ../../../03-exports/aliases-api.include
+.. include:: ../../../03-exports/roles.include
+
+.. _freq_discovery_questions:
+
+Discovery Frequently Asked Questions
+====================================
+
+
+.. collapse::  What are the two main phases involved in the discovery process of Fast DDS?
+
+
+
+
+    |br|
+
+    The two main phases involved in the discovery process of Fast DDS are the Participant Discovery Phase (PDP) and the Endpoint Discovery Phase (EDP).
+    The Participant Discovery Phase (PDP) involves |DomainParticipants-api| recognizing each other by sending periodic announcement messages with their unicast addresses. Matching occurs when they are in the same DDS Domain, using multicast by default, though unicast and announcement frequency can be customized. In the Endpoint Discovery Phase (EDP), DataWriters and DataReaders acknowledge each other by sharing information about topics and data types over the established channels. Matching endpoints with the same topic and data type are then ready to exchange user data. For further information, go to :ref:`disc_phases`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What discovery mechanisms does FastDDS provide?
+
+
+
+
+    |br|
+
+    There are four discovery mechanisms in DDS: Simple Discovery, which follows the RTPS standard for both PDP and EDP, ensuring compatibility with other DDS implementations; Static Discovery, which uses the Simple Participant Discovery Protocol (SPDP) but skips the Endpoint Discovery phase if endpoint details are pre-known; Discovery Server, which employs a centralized server for meta traffic discovery; and Manual Discovery, which disables the PDP and requires users to manually match RTPS participants and endpoints using external meta-information channels. For further information, go to :ref:`disc_mechanisms`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is an initial peer list?
+
+
+
+
+    |br|
+
+    An initial peer list contains one or more IP-port address pairs corresponding to remote DomainParticipants PDP discovery listening resources, so that the local DomainParticipant will not only send its PDP traffic to the default multicast address-port specified by its domain, but also to all the IP-port address pairs specified in the initial peers list. For further information, go to :ref:`simple_disc_settings`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  When could a static configuration of peers be used?
+
+
+
+
+    |br|
+
+    When all DataWriters and DataReaders, and their Topics and data types, are known beforehand, the EDP phase can be replaced with a static configuration of peers. For further information, go to :ref:`discovery_static`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is the primary difference between the Discovery Server mechanism and Simple discovery mechanism in terms of managing metatraffic?
+
+
+
+
+    |br|
+
+    The Discovery Server mechanism is based on a client-server discovery paradigm, the metatraffic is managed by one or several server DomainParticipants, as opposed to simple discovery, where metatraffic is exchanged using a message broadcast mechanism like an IP multicast protocol. For further information, go to :ref:`discovery_server`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is the primary function of a Discovery Server in the DDS architecture?
+
+
+
+
+    |br|
+
+    The role of the server is to redistribute its clients' discovery information to its known clients and servers. For further information, go to :ref:`discovery_server`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is the primary purpose of a "BACKUP" server in the Discovery Server mechanism?
+
+
+
+
+    |br|
+
+    A ``BACKUP`` server is a server that persists its discovery database into a file. This type of server can load the network graph from a file on start-up without the need of receiving any client's information. For further information, go to :ref:`discovery_server`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is a client in this context?
+
+
+
+
+    |br|
+
+    A ``CLIENT`` is a participant that connects to one or more servers from which it receives only the discovery information they require to establish communication with matching endpoints. For further information, go to :ref:`discovery_server`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is the difference between a CLIENT and a SUPER_CLIENT?
+
+
+
+
+    |br|
+
+    A ``SUPER_CLIENT`` is a client that receives the discovery information known by the server, in opposition to clients, which only receive the information they need. For further information, go to :ref:`discovery_server`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is the purpose of each server specifying its own locator list in the context of discovery configuration?
+
+
+
+
+    |br|
+
+    Each client must keep a list of locators associated to the servers to which it wants to link. Each server specifies its own locator list which must be populated with ``RemoteServerAttributes`` objects with a valid ``metatrafficUnicastLocatorList`` or ``metatrafficMulticastLocatorList``. In XML the server list and its elements are simultaneously specified. For further information, go to :ref:`discovery_server`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is the typical interval of time between discovery messages sent by clients to servers, as described in the text?
+
+
+
+
+    |br|
+
+    As explained above the clients send discovery messages to the servers at regular intervals (ping period) until they receive message reception acknowledgement. The default value for this period is 450 ms. For further information, go to :ref:`discovery_server`.
+
+|

docs/fastdds/faq/environment_variables/environment_variables.rst

@@ -0,0 +1,98 @@
+.. include:: ../../../03-exports/aliases.include
+.. include:: ../../../03-exports/aliases-api.include
+.. include:: ../../../03-exports/roles.include
+
+.. _freq_env_variables_questions:
+
+Environment Variables Frequently Asked Questions
+================================================
+
+
+.. collapse::  What are the most important environment variables that affect the behavior of Fast DDS?
+
+
+
+
+    |br|
+
+    ``FASTDDS_DEFAULT_PROFILES_FILE``, ``SKIP_DEFAULT_XML``, ``FASTDDS_BUILTIN_TRANSPORTS``, ``ROS_DISCOVERY_SERVER``, ``ROS_SUPER_CLIENT``, ``FASTDDS_STATISTICS``, ``FASTDDS_ENVIRONMENT_FILE``. For further information, go to :ref:`env_vars`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is the purpose of the "FASTDDS_DEFAULT_PROFILES_FILE" environment variable?
+
+
+
+
+    |br|
+
+    Defines the location of the default profile configuration XML file. For further information, go to :ref:`env_vars_fastdds_default_profiles_file`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What happens when the variable "SKIP_DEFAULT_XML" is set to 1?
+
+
+
+
+    |br|
+
+    Skips looking for a default profile configuration XML file. If this variable is set to 1, Fast DDS will load the configuration parameters directly from the classes' definitions without looking for the ``DEFAULT_FASTDDS_PROFILES.xml`` in the working directory. For further information, go to :ref:`env_vars_skip_default_xml`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is the primary purpose of the FASTDDS_BUILTIN_TRANSPORTS environment variable?
+
+
+
+
+    |br|
+
+    Setting this variable allows to modify the builtin transports that are initialized during the |DomainParticipant-api| creation. For further information, go to :ref:`env_vars_builtin_transports`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is the purpose of the "ROS_DISCOVERY_SERVER" environment variable?
+
+
+
+
+    |br|
+
+    Setting this variable configures the DomainParticipant to connect to one or more servers using the Discovery Server discovery mechanism. For further information, go to :ref:`env_vars_ros_discovery_server`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What happens to a "DomainParticipant" when its discovery protocol is set to "SIMPLE" and "ROS_SUPER_CLIENT" is set to TRUE?
+
+
+
+
+    |br|
+
+    If the DomainParticipant's discovery protocol is set to ``SIMPLE``, and ``ROS_SUPER_CLIENT`` is set to ``TRUE``, the participant is automatically promoted to a ``SUPER_CLIENT``. For further information, go to :ref:`env_vars_ros_super_client`.
+
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What is the purpose of setting the "FASTDDS_STATISTICS" environment variable, according to the provided information?
+
+
+
+
+    |br|
+
+    Setting this variable configures the |DomainParticipant-api| to enable the statistics DataWriters which topics are contained in the list set in this environment variable. For further information, go to :ref:`env_vars_fastdds_statistics`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. collapse::  What happens when you set the "FASTDDS_ENVIRONMENT_FILE" environment variable to a JSON file?
+
+
+
+
+    |br|
+
+    Setting this environment variable to an existing ``json`` file allows to load the environment variables from the file instead of from the environment. For further information, go to :ref:`env_vars_fastdds_environment_file`.
+
+|

docs/fastdds/faq/faq.rst

@@ -0,0 +1,26 @@
+.. _frequently_asked_questions:
+
+Frequently Asked Questions
+==========================
+
+This section answers to frequently asked questions about FastDDS.
+
+
+.. toctree::
+    :caption: Frequently Asked Questions
+    :maxdepth: 2
+
+    getting_started/getting_started
+    dds_layer/dds_layer
+    rtps_layer/rtps_layer
+    transport_layer/transport_layer
+    discovery/discovery
+    persistence_service/persistence_service
+    security/security
+    logging/logging
+    xml_profiles/xml_profiles
+    environment_variables/environment_variables
+    statistics_module/statistics_module
+    xtypes/xtypes
+
+