Add Python API reference [13580] (#318)

* Refs #13380. Add python bindings API Signed-off-by: Ricardo González Moreno <[email protected]> * Refs #13380. Support RTD Signed-off-by: Ricardo González Moreno <[email protected]> * Refs #13380. Remove warnings when running spelling check Signed-off-by: Ricardo González Moreno <[email protected]> * Refs #13380. Add comments on conf.py Signed-off-by: Ricardo González Moreno <[email protected]> * Refs #13580. Fix wrong branch Signed-off-by: Ricardo González Moreno <[email protected]> * Refs #13580. Fix not removed testing thing Signed-off-by: Ricardo González Moreno <[email protected]> * Refs #13580. Fix not commented line Signed-off-by: Ricardo González Moreno <[email protected]> * Refs #13580. Add info about FASTDDS_PYTHON_BRANCH Signed-off-by: Ricardo González Moreno <[email protected]>
eProsima · Feb 14, 2022 · 02407a6 · 02407a6
1 parent d778875
commit 02407a6
Show file tree

Hide file tree

Showing 124 changed files with 1,281 additions and 10 deletions.
diff --git a/CMakeLists.txt b/CMakeLists.txt
@@ -41,6 +41,10 @@ project(fastdds-docs VERSION "${LIB_VERSION_STR}" LANGUAGES C CXX)
 find_package(fastrtps REQUIRED)
 get_target_property(FAST_INCLUDE_DIR fastrtps INTERFACE_INCLUDE_DIRECTORIES)
 
+find_package(fastdds_python REQUIRED)
+get_target_property(FASTDDS_PYTHON_IMPORTED_LOCATION fastdds_python "LOCATION")
+get_filename_component (FASTDDS_PYTHON_IMPORTED_LOCATION ${FASTDDS_PYTHON_IMPORTED_LOCATION} DIRECTORY)
+
 message(STATUS "Fast DDS include directories: ${FAST_INCLUDE_DIR}")
 file(GLOB_RECURSE HPP_FILES "${FAST_INCLUDE_DIR}/fastdds/**/*.h*")
 
@@ -108,6 +112,7 @@ if (BUILD_DOCUMENTATION)
         ${SPHINX_EXECUTABLE} -b ${FASTDDS_DOCS_BUILDER}
         # Tell Breathe where to find the Doxygen output
         -D breathe_projects.FastDDS=${DOXYGEN_OUTPUT_DIR}/xml
+        -D fastdds_python_imported_location=${FASTDDS_PYTHON_IMPORTED_LOCATION}
         -d "${PROJECT_BINARY_DIR}/doctrees"
         ${SPHINX_SOURCE}
         ${PROJECT_BINARY_DIR}/${FASTDDS_DOCS_BUILDER}

diff --git a/README.md b/README.md
@@ -181,14 +181,20 @@ When this variable is set to `True`, [conf.py](docs/conf.py) will clone Fast DDS
 1. 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.
 1. If the previous fails, fallback to `master`.
 
+Also Fast DDS Python bindings is cloned and follows a similar criteria:
+
+1. Try to checkout to the branch specified by environment variable `FASTDDS_PYTHON_BRANCH`.
+1. 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.
+1. If the previous fails, fallback to `main`.
+
 To simulate ReadTheDocs operation, make sure you do not have a `build` directory.
-Then, set `READTHEDOCS` and `FASTDDS_BRANCH`, and run sphinx:
+Then, set `READTHEDOCS`, `FASTDDS_BRANCH` and `FASTDDS_PYTHON_BRANCH` and run sphinx:
 
 ```bash
 source <path_to_venv>/fastdds-docs-venv/bin/activate
 cd <path_to_docs_repo>/fastdds-docs
 rm -rf build
-READTHEDOCS=True FASTDDS_BRANCH=<branch> sphinx-build \
+READTHEDOCS=True FASTDDS_BRANCH=<branch> FASTDDS_PYTHON_BRANCH=<branch> sphinx-build \
     -b html \
     -D breathe_projects.FastDDS=<abs_path_to_docs_repo>/fastdds-docs/build/doxygen/xml \
     -d <abs_path_to_docs_repo>/fastdds-docs/build/doctrees \

diff --git a/colcon.meta b/colcon.meta
@@ -5,6 +5,13 @@
                 "-DSECURITY=ON",
             ]
         },
+        "fastdds_python":
+        {
+            "cmake-args":
+            [
+                "-DBUILD_DOCUMENTATION=ON",
+            ]
+        },
         "fastdds-docs":
         {
             "cmake-args":

diff --git a/colcon.pkg b/colcon.pkg
@@ -1,5 +1,5 @@
 {
     "name": "fastdds-docs",
     "type": "cmake",
-    "dependencies": ["fastrtps"]
+    "dependencies": ["fastrtps", "fastdds_python"]
 }
diff --git a/docs/conf.py b/docs/conf.py
@@ -22,11 +22,15 @@
 import pathlib
 import shutil
 import subprocess
+import sys
 
 import git
 
 import requests
 
+# Add configuration variables which can be set when calling sphinx.
+def setup(app):
+    app.add_config_value('fastdds_python_imported_location', None, '')
 
 def download_css(html_css_dir):
     """
@@ -145,6 +149,7 @@ def configure_doxyfile(
 project_binary_dir = os.path.abspath('{}/../build'.format(script_path))
 output_dir = os.path.abspath('{}/doxygen'.format(project_binary_dir))
 doxygen_html = os.path.abspath('{}/html/doxygen'.format(project_binary_dir))
+fastdds_python_imported_location = None
 
 # Doxyfile
 doxyfile_in = os.path.abspath(
@@ -170,19 +175,27 @@ def configure_doxyfile(
         )
     )
 
+    fastdds_python_repo_name = os.path.abspath(
+        '{}/fastdds_python'.format(
+            project_binary_dir
+        )
+    )
+
     # Remove repository if exists
     if os.path.isdir(fastdds_repo_name):
         print('Removing existing repository in {}'.format(fastdds_repo_name))
         shutil.rmtree(fastdds_repo_name)
+    if os.path.isdir(fastdds_python_repo_name):
+        print('Removing existing repository in {}'.format(fastdds_python_repo_name))
+        shutil.rmtree(fastdds_python_repo_name)
 
     # Create necessary directory path
     os.makedirs(os.path.dirname(fastdds_repo_name), exist_ok=True)
-    # Create a COLCON_IGNORE file just in case
-    open(
-        os.path.abspath('{}/COLCON_IGNORE'.format(project_binary_dir)), 'w'
-    ).close()
+    os.makedirs(os.path.dirname(fastdds_python_repo_name), exist_ok=True)
 
-    # Clone repository
+    # Clone repositories
+
+    ## Fast DDS
     print('Cloning Fast DDS')
     fastdds = git.Repo.clone_from(
         'https://github.com/eProsima/Fast-DDS.git',
@@ -218,6 +231,38 @@ def configure_doxyfile(
     print('Checking out Fast DDS branch "{}"'.format(fastdds_branch))
     fastdds.refs[fastdds_branch].checkout()
 
+    ## Fast DDS Python Bindings
+    print('Cloning Fast DDS Python Bindings')
+    fastdds_python = git.Repo.clone_from(
+        'https://github.com/eProsima/Fast-DDS-python.git',
+        fastdds_python_repo_name,
+    )
+
+    # User specified Fast DDS branch
+    fastdds_python_branch = os.environ.get('FASTDDS_PYTHON_BRANCH', None)
+
+    # First try to checkout to ${FASTDDS_PYTHON_BRANCH}
+    # Else try with current documentation branch
+    # Else checkout to master
+    if (fastdds_python_branch and
+            fastdds_python.refs.__contains__('origin/{}'.format(fastdds_python_branch))):
+        fastdds_python_branch = 'origin/{}'.format(fastdds_python_branch)
+    elif (docs_branch and
+            fastdds_python.refs.__contains__('origin/{}'.format(docs_branch))):
+        fastdds_python_branch = 'origin/{}'.format(docs_branch)
+    else:
+        print(
+            'Fast DDS Python does not have either "{}" or "{}" branches'.format(
+                fastdds_python_branch,
+                docs_branch
+            )
+        )
+        fastdds_python_branch = 'origin/main'
+
+    # Actual checkout
+    print('Checking out Fast DDS Python branch "{}"'.format(fastdds_python_branch))
+    fastdds_python.refs[fastdds_python_branch].checkout()
+
     os.makedirs(os.path.dirname(output_dir), exist_ok=True)
     os.makedirs(os.path.dirname(doxygen_html), exist_ok=True)
 
@@ -233,11 +278,29 @@ def configure_doxyfile(
     # Generate doxygen documentation
     subprocess.call('doxygen {}'.format(doxyfile_out), shell=True)
 
+    # Generate SWIG code.
+    subprocess.call('swig -python -doxygen -I{}/include -outdir {}/fastdds_python/src/swig -c++ -interface \
+            _fastdds_python -o {}/fastdds_python/src/swig/fastddsPYTHON_wrap.cxx \
+            {}/fastdds_python/src/swig/fastdds.i'.format(
+                fastdds_repo_name,
+                fastdds_python_repo_name,
+                fastdds_python_repo_name,
+                fastdds_python_repo_name
+                ), shell=True)
+    fastdds_python_imported_location = '{}/fastdds_python/src/swig'.format(fastdds_python_repo_name)
+    autodoc_mock_imports = ["_fastdds_python"]
+
+
+
 breathe_projects = {
     'FastDDS': os.path.abspath('{}/xml'.format(output_dir))
 }
 breathe_default_project = 'FastDDS'
 
+# Tell `autodoc` where is the Pydoc documentation if it was set.
+if fastdds_python_imported_location:
+    sys.path.insert(0, fastdds_python_imported_location)
+
 # -- General configuration ------------------------------------------------
 
 # If your documentation needs a minimal Sphinx version, state it here.
@@ -250,7 +313,9 @@ def configure_doxyfile(
 extensions = [
     'breathe',
     'sphinxcontrib.plantuml',
+    'sphinx.ext.autodoc' # Document Pydoc documentation from Python bindings.
 ]
+
 try:
     import sphinxcontrib.spelling  # noqa: F401
     extensions.append('sphinxcontrib.spelling')
@@ -268,6 +333,12 @@ def configure_doxyfile(
 except ImportError:
     pass
 
+# Default behaviour for `autodoc`: always show documented members.
+autodoc_default_options = {
+        'members': True,
+        'undoc-members': False,
+        }
+
 plantuml = '/usr/bin/plantuml -Djava.awt.headless=true '
 plantuml_output_format = "svg"
 
@@ -360,6 +431,13 @@ def configure_doxyfile(
     'cpp.parse_function_declaration'
 ]
 
+# Check if we are checking the spelling. In this case...
+if 'spelling' in sys.argv:
+    # Exclude Python API Reference because `autodoc` shows warnings.
+    exclude_patterns.append('fastdds/python_api_reference/dds_pim/*')
+    # Avoid the warning of a wrong reference in the TOC entries, because fails the Python API Reference reference.
+    suppress_warnings.append('toc.excluded')
+
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 

diff --git a/docs/fastdds/api_reference/api_reference.rst b/docs/fastdds/api_reference/api_reference.rst
@@ -1,7 +1,7 @@
 .. _api_reference:
 
-API Reference
-=============
+C++ API Reference
+=================
 
 *Fast DDS*, as a Data Distribution Service (DDS) standard implementation, exposes the DDS Data-Centric Publish-Subscribe
 (DCPS) Platform Independent Model (PIM) API, as specified in the

diff --git a/docs/fastdds/python_api_reference/dds_pim/core/core.rst b/docs/fastdds/python_api_reference/dds_pim/core/core.rst
@@ -0,0 +1,13 @@
+Core
+====
+
+.. toctree::
+
+   /fastdds/python_api_reference/dds_pim/core/entity.rst
+   /fastdds/python_api_reference/dds_pim/core/domainentity.rst
+   /fastdds/python_api_reference/dds_pim/core/policy/policy.rst
+   /fastdds/python_api_reference/dds_pim/core/status/status.rst
+   /fastdds/python_api_reference/dds_pim/core/loanablearray.rst
+   /fastdds/python_api_reference/dds_pim/core/loanablecollection.rst
+   /fastdds/python_api_reference/dds_pim/core/loanablesequence.rst
+   /fastdds/python_api_reference/dds_pim/core/stackallocatedsequence.rst
diff --git a/docs/fastdds/python_api_reference/dds_pim/core/domainentity.rst b/docs/fastdds/python_api_reference/dds_pim/core/domainentity.rst
@@ -0,0 +1,9 @@
+
+.. _python_api_pim_domainentity:
+
+.. rst-class:: api-ref
+
+DomainEntity
+------------
+
+.. autoclass:: fastdds.DomainEntity
diff --git a/docs/fastdds/python_api_reference/dds_pim/core/entity.rst b/docs/fastdds/python_api_reference/dds_pim/core/entity.rst
@@ -0,0 +1,8 @@
+.. _python_api_pim_entity:
+
+.. rst-class:: api-ref
+
+Entity
+------
+
+.. autoclass:: fastdds.Entity
diff --git a/docs/fastdds/python_api_reference/dds_pim/core/loanablearray.rst b/docs/fastdds/python_api_reference/dds_pim/core/loanablearray.rst
@@ -0,0 +1,9 @@
+.. _python_api_pim_loanablearray:
+
+.. rst-class:: api-ref
+
+LoanableArray
+-------------
+
+.. TODO
+   .. autoclass:: fastdds.LoanableArray
diff --git a/docs/fastdds/python_api_reference/dds_pim/core/loanablecollection.rst b/docs/fastdds/python_api_reference/dds_pim/core/loanablecollection.rst
@@ -0,0 +1,8 @@
+.. _python_api_pim_loanablecollection:
+
+.. rst-class:: api-ref
+
+LoanableCollection
+------------------
+
+.. autoclass:: fastdds.LoanableCollection
diff --git a/docs/fastdds/python_api_reference/dds_pim/core/loanablesequence.rst b/docs/fastdds/python_api_reference/dds_pim/core/loanablesequence.rst
@@ -0,0 +1,9 @@
+.. _python_api_pim_loanablesequence:
+
+.. rst-class:: api-ref
+
+LoanableSequence
+------------------
+
+.. TODO
+   .. autoclass:: fastdds.LoanableSequence
diff --git a/docs/fastdds/python_api_reference/dds_pim/core/policy/datarepresentationid.rst b/docs/fastdds/python_api_reference/dds_pim/core/policy/datarepresentationid.rst
@@ -0,0 +1,12 @@
+.. _python_api_pim_datarepresentationid:
+
+.. rst-class:: api-ref
+
+DataRepresentationId
+--------------------
+
+.. autoclass:: fastdds.XCDR_DATA_REPRESENTATION
+
+.. autoclass:: fastdds.XML_DATA_REPRESENTATION
+
+.. autoclass:: fastdds.XCDR2_DATA_REPRESENTATION
diff --git a/...astdds/python_api_reference/dds_pim/core/policy/datarepresentationqospolicy.rst b/...astdds/python_api_reference/dds_pim/core/policy/datarepresentationqospolicy.rst
@@ -0,0 +1,8 @@
+.. _python_api_pim_datarepresentationqospolicy:
+
+.. rst-class:: api-ref
+
+DataRepresentationQosPolicy
+---------------------------
+
+.. autoclass:: fastdds.DataRepresentationQosPolicy
diff --git a/docs/fastdds/python_api_reference/dds_pim/core/policy/datasharingkind.rst b/docs/fastdds/python_api_reference/dds_pim/core/policy/datasharingkind.rst
@@ -0,0 +1,12 @@
+.. _python_api_pim_datasharingkind:
+
+.. rst-class:: api-ref
+
+DataSharingKind
+---------------
+
+.. autoclass:: fastdds.AUTO
+
+.. autoclass:: fastdds.ON
+
+.. autoclass:: fastdds.OFF
diff --git a/docs/fastdds/python_api_reference/dds_pim/core/policy/datasharingqospolicy.rst b/docs/fastdds/python_api_reference/dds_pim/core/policy/datasharingqospolicy.rst
@@ -0,0 +1,8 @@
+.. _python_api_pim_datasharingqospolicy:
+
+.. rst-class:: api-ref
+
+DataSharingQosPolicy
+--------------------
+
+.. autoclass:: fastdds.DataSharingQosPolicy
diff --git a/docs/fastdds/python_api_reference/dds_pim/core/policy/deadlineqospolicy.rst b/docs/fastdds/python_api_reference/dds_pim/core/policy/deadlineqospolicy.rst
@@ -0,0 +1,8 @@
+.. _python_api_pim_deadlineqospolicy:
+
+.. rst-class:: api-ref
+
+DeadlineQosPolicy
+-----------------
+
+.. autoclass:: fastdds.DeadlineQosPolicy
diff --git a/.../fastdds/python_api_reference/dds_pim/core/policy/destinationorderqospolicy.rst b/.../fastdds/python_api_reference/dds_pim/core/policy/destinationorderqospolicy.rst
@@ -0,0 +1,8 @@
+.. _python_api_pim_destinationorderqospolicy:
+
+.. rst-class:: api-ref
+
+DestinationOrderQosPolicy
+-------------------------
+
+.. autoclass:: fastdds.DestinationOrderQosPolicy
diff --git a/...tdds/python_api_reference/dds_pim/core/policy/destinationorderqospolicykind.rst b/...tdds/python_api_reference/dds_pim/core/policy/destinationorderqospolicykind.rst
@@ -0,0 +1,11 @@
+.. _python_api_pim_destinationorderqospolicykind:
+
+.. rst-class:: api-ref
+
+DestinationOrderQosPolicyKind
+-----------------------------
+
+.. autoclass:: fastdds.BY_RECEPTION_TIMESTAMP_DESTINATIONORDER_QOS
+
+.. autoclass:: fastdds.BY_SOURCE_TIMESTAMP_DESTINATIONORDER_QOS
+
diff --git a/...stdds/python_api_reference/dds_pim/core/policy/disablepositiveacksqospolicy.rst b/...stdds/python_api_reference/dds_pim/core/policy/disablepositiveacksqospolicy.rst
@@ -0,0 +1,8 @@
+.. _python_api_pim_disablepositiveacksqospolicy:
+
+.. rst-class:: api-ref
+
+DisablePositiveACKsQosPolicy
+----------------------------
+
+.. autoclass:: fastdds.DisablePositiveACKsQosPolicy
diff --git a/docs/fastdds/python_api_reference/dds_pim/core/policy/durabilityqospolicy.rst b/docs/fastdds/python_api_reference/dds_pim/core/policy/durabilityqospolicy.rst
@@ -0,0 +1,8 @@
+.. _python_api_pim_durabilityqospolicy:
+
+.. rst-class:: api-ref
+
+DurabilityQosPolicy
+-------------------
+
+.. autoclass:: fastdds.DurabilityQosPolicy