Enhance Fast DDS docs with a FAQs section covering every subsection (#…

…902) * Add FAQs section (#883) * Refs #21416: Add FAQs section Signed-off-by: Denisa <[email protected]> * FAQ section Signed-off-by: Denisa <[email protected]> * Refs #21416: Frequently Asked Questions-add review comments Signed-off-by: Denisa <[email protected]> --------- Signed-off-by: Denisa <[email protected]> Co-authored-by: Denisa <[email protected]> * [21416] Add FAQs section (#883) (#891) * Refs #21416: Add FAQs section Signed-off-by: Denisa <[email protected]> * FAQ section Signed-off-by: Denisa <[email protected]> * Refs #21416: Frequently Asked Questions-add review comments Signed-off-by: Denisa <[email protected]> --------- Signed-off-by: Denisa <[email protected]> Co-authored-by: Denisa <[email protected]> * Refs #21416: Fix README.md Signed-off-by: Carlosespicur <[email protected]> * Add review changes Signed-off-by: Denisa <[email protected]> * Change format to adapt to standard documentation Signed-off-by: Denisa <[email protected]> --------- Signed-off-by: Denisa <[email protected]> Signed-off-by: Carlosespicur <[email protected]> Co-authored-by: Carlosespicur <[email protected]>
eProsima · Sep 26, 2024 · 5e9e5db · 5e9e5db
1 parent 6e60196
commit 5e9e5db
Show file tree

Hide file tree

Showing 21 changed files with 1,784 additions and 5 deletions.
diff --git a/docs/02-formalia/titlepage.rst b/docs/02-formalia/titlepage.rst
@@ -212,3 +212,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.
diff --git a/docs/03-exports/aliases-api.include b/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>`

diff --git a/docs/conf.py b/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
@@ -471,6 +471,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

diff --git a/...erence/rtps/participant/participantdiscoveryinfo/ParticipantDiscoveryStatus.rst b/...erence/rtps/participant/participantdiscoveryinfo/ParticipantDiscoveryStatus.rst
@@ -1,7 +1,7 @@
 .. rst-class:: api-ref
 
 ParticipantDiscoveryStatus
-----------------------------
+--------------------------
 
 .. doxygenenum:: eprosima::fastdds::rtps::ParticipantDiscoveryStatus
  :project: FastDDS
diff --git a/docs/fastdds/faq/dds_layer/dds_layer.rst b/docs/fastdds/faq/dds_layer/dds_layer.rst
diff --git a/docs/fastdds/faq/discovery/discovery.rst b/docs/fastdds/faq/discovery/discovery.rst
@@ -0,0 +1,104 @@
+.. 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, refer 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, refer 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, refer 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, refer 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, refer 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, refer 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, refer 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, refer 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, refer 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, refer 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, refer 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, refer to :ref:`discovery_server`.
+
+|
diff --git a/docs/fastdds/faq/environment_variables/environment_variables.rst b/docs/fastdds/faq/environment_variables/environment_variables.rst
@@ -0,0 +1,65 @@
+.. 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, refer 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, refer 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, refer 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, refer 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, refer 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, refer 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, refer 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, refer to :ref:`env_vars_fastdds_environment_file`.
+
+|
diff --git a/docs/fastdds/faq/faq.rst b/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
+ discovery/discovery
+ transport_layer/transport_layer
+ persistence_service/persistence_service
+ security/security
+ logging/logging
+ xml_profiles/xml_profiles
+ environment_variables/environment_variables
+ statistics_module/statistics_module
+ xtypes/xtypes
+
+