eProsima Fast DDS API Reference

eprosima Fast DDS (formerly Fast RTPS) is a C++ implementation of the DDS (Data Distribution Service) standard of the OMG (Object Management Group). eProsima Fast DDS implements the RTPS (Real Time Publish Subscribe) protocol, which provides publisher-subscriber communications over unreliable transports such as UDP, as defined and maintained by the Object Management Group (OMG) consortium. RTPS is also the wire interoperability protocol defined for the Data Distribution Service (DDS) standard. eProsima Fast DDS exposes an API to access the RTPS protocol directly, giving the user full access to the protocol internals.

Some of the main features of this library are:

Configurable best-effort and reliable publish-subscribe communication policies for real-time applications.
Plug and play connectivity so that any new applications are automatically discovered by any other members of the network.
Modularity and scalability to allow continuous growth with complex and simple devices in the network.
Configurable network behavior and interchangeable transport layer: Choose the best protocol and system input/output channel combination for each deployment.
Two API Layers: a high-level Publisher-Subscriber one focused on usability (DDS) and a lower-level Writer-Reader one that provides finer access to the inner workings of the RTPS protocol.

eProsima Fast DDS has been adopted by multiple organizations in many sectors including these important cases:

Robotics: ROS (Robotic Operating System) as their default middleware for ROS2.
EU R&D: FIWARE Incubated GE.

You can find all the library's source code on our GitHub repository.

The documentation is built using Sphinx, and it is hosted at Read the Docs. The online documentation generated with this project can be found in Fast DDS documentation.

Installation Guide
Getting Started
Generating documentation in other formats
Running documentation tests
Simulating Read the Docs
Contributing

Installation Guide

In order to build and test the Fast DDS API reference documentation, some dependencies must be installed beforehand:

sudo apt update
sudo apt install -y \
    git \
    gcc \
    g++ \
    cmake \
    curl \
    wget \
    libasio-dev \
    libtinyxml2-dev \
    doxygen \
    python3 \
    python3-pip \
    python3-venv \
    python3-sphinxcontrib.spelling \
    imagemagick

Clone the repository

cd ~
git clone https://github.com/eProsima/Fast-RTPS-docs fast-dds-docs-api

Create a virtual environment and install python3 dependencies.

cd ~/fast-dds-docs-api
python3 -m venv fast-dds-docs-api-venv
source fast-dds-docs-api-venv/bin/activate
pip3 install -r docs/requirements.txt
cd fast-dds-docs-api-venv/lib/<python-version>/site-packages
curl https://patch-diff.githubusercontent.com/raw/sphinx-doc/sphinx/pull/7851.diff | git apply
cd -

The version of python3 used in the virtual environment can be seen by running the following command within the virtual environment:

python3 -V

Troubleshooting

Python versions 3.7 and newer produce Duplicate declaration and Error when parsing function declaration warnings when running make test, this is due to a difference in the Sphinx 3.0.3 module code which prevents the patch from working.

Getting Started

To generate the documentation in a HTML format for a specific branch of Fast DDS run:

cd ~/fast-dds-docs-api
source fast-dds-docs-api-venv/bin/activate
make html

Selecting Fast DDS branch

It is possible to specify the Fast DDS branch for which the documentation is generated via the environment variable FASTDDS_BRANCH.

cd ~/fast-dds-docs-api
source fast-dds-docs-api-venv/bin/activate
FASTDDS_BRANCH=<branch> make help

Generating documentation in other formats

The documentation can be generated in several formats such as HTML, PDF, LaTex, etc. For a complete list of targets run:

cd ~/fast-dds-docs-api
make help

Once you have selected a format, generate the documentation with:

cd ~/fast-dds-docs-api
source fast-dds-docs-api-venv/bin/activate
FASTDDS_BRANCH=<branch> make <output_format>

Running documentation tests

DISCLAIMER: In order to run documentation tests, access to eProsima's intranet is required.

This repository provides a set of tests that verify that:

The RST follows the style guidelines
The HTML is built correctly
The C++ snippets compile against the library's version
The XML snippets define valid configurations

Run the tests by:

cd ~/fast-dds-docs-api
source fast-dds-docs-api-venv/bin/activate
FASTDDS_BRANCH=<branch> make test

Simulating Read the Docs

Read the Docs generates the documentation using Sphinx and conf.py. This means that it does not execute make and therefore Fast DDS is not downloaded for API reference documentation generation. conf.py provides some extra logic to download Fast DDS and generate the Doxygen documentation when running on a Read the Docs environment. This is done by means of the environment variable READTHEDOCS. When this variable is set to True, conf.py will clone Fast DDS in build/code/external/eprosima/src/ (same place as CMake) and will set it to a branch applying the following criteria:

Try to checkout to the branch specified by FASTDDS_BRANCH.
If the variable is not set, or the branch does not exist, try to checkout to a branch with the same name as the current branch on this repository.
If the previous fails, fallback to master.

To simulating Read the Docs operation, make sure you do not have a build directory.

cd ~/fast-dds-docs-api
rm -rf build

Then, set READTHEDOCS, FASTDDS_BRANCH and run sphinx:

READTHEDOCS=True FASTDDS_BRANCH=<branch> sphinx-build \
    -b html \
    -Dbreathe_projects.FastDDS=<abs_path_to_docs_repo>/fast-dds-docs-api/build/code/doxygen/xml \
    -d <abs_path_to_docs_repo>/fast-dds-docs-api/build/doctrees \
    docs <abs_path_to_docs_repo>/fast-dds-docs-api/build/html

Contributing

If you are interested in making some contributions, either in the form of an issue or a pull request, please refer to our Contribution Guidelines.

eProsima/fast-dds-docs-api