[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/03-exports/aliases-api.include

@@ -885,6 +885,7 @@
 .. |EntityId_t-api| replace:: :cpp:struct:`EntityId_t<eprosima::fastdds::rtps::EntityId_t>`
 .. |InitialAnnouncementConfig-api| replace:: :cpp:struct:`InitialAnnouncementConfig<eprosima::fastdds::rtps::InitialAnnouncementConfig>`
 .. |InitialAnnouncementConfig::period-api| replace:: :cpp:member:`period<eprosima::fastdds::rtps::InitialAnnouncementConfig::period>`
+.. |InitialAnnouncementConfig::count-api| replace:: :cpp:member:`count<eprosima::fastdds::rtps::InitialAnnouncementConfig::count>`
 .. |BuiltinAttributes-api| replace:: :cpp:class:`BuiltinAttributes<eprosima::fastdds::rtps::BuiltinAttributes>`
 .. |BuiltinAttributes::discovery_config-api| replace:: :cpp:member:`discovery_config<eprosima::fastdds::rtps::BuiltinAttributes::discovery_config>`
 .. |BuiltinAttributes::metatrafficUnicastLocatorList-api| replace:: :cpp:member:`metatrafficUnicastLocatorList<eprosima::fastdds::rtps::BuiltinAttributes::metatrafficUnicastLocatorList>`

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,140 @@
+.. 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:: How can you improve the chances of successful participant discovery when using the SIMPLE discovery protocol, and what role do initial announcements play in this process?
+
+
+    |br|
+
+    To improve the chances of successful participant discovery when using the SIMPLE discovery protocol, you can configure initial announcements to send multiple discovery messages at short intervals. This increases the likelihood that DomainParticipants will detect each other despite potential network disruptions or message loss. By adjusting the |InitialAnnouncementConfig::count-api| (number of announcements) and |InitialAnnouncementConfig::period-api| (interval between announcements), you can optimize discovery reliability during startup. For further information, go to :ref:`simple_disc_settings`.
+
+-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
+
+.. 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 primary function of a Discovery Server in the DDS architecture is to centralize and redistribute discovery information among DomainParticipants, ensuring efficient communication between clients and servers. The server collects discovery data from clients (and other servers) and redistributes it to relevant participants, running a "matching" algorithm to provide only the necessary information for DataWriters and DataReaders to establish communication. It also facilitates server-to-server connections, enabling a more scalable discovery process across the network. 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`.
+
+|