Add ament_cmake_python user documentation (backport #1943) (#1948)

Signed-off-by: Christophe Bedard <bedard.christophe@gmail.com>
(cherry picked from commit 10b3260)

source/Concepts/About-Build-System.rst

@@ -98,6 +98,7 @@ Here a list of the |packages| in the repository along with a short description:
 -  ``ament_cmake_python``
 
    - provides CMake functions for |packages| that contain Python code
+   - see the `ament_cmake_python user documentation <../Guides/Ament-CMake-Python-Documentation>`__
 
 -  ``ament_cmake_test``
 

source/Guides.rst

@@ -19,6 +19,7 @@ If you are new and looking to learn the ropes, start with the :ref:`Tutorials <T
    Guides/Installation-Troubleshooting
    Guides/Developing-a-ROS-2-Package
    Guides/Ament-CMake-Documentation
+   Guides/Ament-CMake-Python-Documentation
    Guides/Launch-files-migration-guide
    Guides/Launch-file-different-formats
    Guides/Parameters-YAML-files-migration-guide

source/Guides/Ament-CMake-Python-Documentation.rst

@@ -0,0 +1,64 @@
+ament_cmake_python user documentation
+=====================================
+
+``ament_cmake_python`` is a package that provides CMake functions for packages of the ``ament_cmake`` build type that contain Python code.
+See the `ament_cmake user documentation <Ament-CMake-Documentation>`__ for more information.
+
+.. note::
+
+   Pure Python packages should use the ``ament_python`` build type in most cases.
+   To create an ``ament_python`` package, see `Creating your first ROS 2 package <../Tutorials/Creating-Your-First-ROS2-Package>`__.
+   ``ament_cmake_python`` should only be used in cases where that is not possible, like when mixing C/C++ and Python code.
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+
+Basics
+------
+
+Basic project outline
+^^^^^^^^^^^^^^^^^^^^^
+
+The outline of a package called "my_project" with the ``ament_cmake`` build type that uses ``ament_cmake_python`` looks like:
+
+.. code-block::
+
+   .
+   └── my_project
+       ├── CMakeLists.txt
+       ├── package.xml
+       └── my_project
+           ├── __init__.py
+           └── my_script.py
+
+The ``__init__.py`` file can be empty, but it is needed to `make Python treat the directory containing it as a package <https://docs.python.org/3/tutorial/modules.html#packages>`__.
+There can also be a ``src`` or ``include`` directory alongside the ``CMakeLists.txt`` which holds C/C++ code.
+
+Using ament_cmake_python
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+The package must declare a dependency on ``ament_cmake_python`` in its ``package.xml``.
+
+.. code-block:: xml
+
+   <buildtool_depend>ament_cmake_python</buildtool_depend>
+
+The ``CMakeLists.txt`` should contain:
+
+.. code-block:: cmake
+
+   find_package(ament_cmake_python REQUIRED)
+   # ...
+   ament_python_install_package(${PROJECT_NAME})
+
+The argument to ``ament_python_install_package()`` is the name of the directory alongside the ``CMakeLists.txt`` that contains the Python file.
+In this case, it is ``my_project``, or ``${PROJECT_NAME}``.
+
+Then, another Python package that correctly depends on ``my_project`` can use it as a normal Python module:
+
+.. code-block:: python
+
+   from my_project.my_script import my_function
+
+Assuming ``my_script.py`` contains a function called ``my_function()``.