added core content to concepts, renamed files to match (ros2#1010)

Signed-off-by: maryaB-osr <[email protected]>

Author: maryaB-osr

global_substitutions.txt

@@ -0,0 +1,17 @@
+.. |ament packages| replace:: :term:`ament packages <ament package>`
+
+.. |API| replace:: :term:`API`
+.. |APIs| replace:: :term:`APIs <API>`
+
+.. |client library| replace:: :term:`client library <client_library>`
+.. |client libraries| replace:: :term:`client libraries <client_library>`
+
+.. |GitHub| replace:: GitHub
+.. _GitHub: https://github.com/
+
+.. |package| replace:: :term:`package`
+.. |packages| replace:: :term:`packages <package>`
+
+.. |REPs| replace:: :term:`REPs <REP>`
+
+.. |rclcpp| replace:: :term:`rclcpp`

source/Concepts.rst

@@ -3,35 +3,42 @@
 Concepts
 ========
 
-The following "Concepts" pages provide an overview for key aspects of ROS 2.
-Concept overviews will help you understand the "big picture" idea of ROS 2 systems.
+Conceptual overviews provide general background information about key aspects of ROS 2:
 
 .. toctree::
    :maxdepth: 1
 
-   Concepts/DDS-and-ROS-middleware-implementations
+   Concepts/About-Different-Middleware-Vendors
+   Concepts/About-Logging
    Concepts/About-Quality-of-Service-Settings
+   Concepts/About-ROS-2-Client-Libraries
    Concepts/About-ROS-Interfaces
-   Concepts/About-Topic-Statistics
-   Concepts/ROS-2-Client-Libraries
-   Concepts/Logging
    Concepts/About-ROS-2-Parameters
+   Concepts/About-Topic-Statistics
+
+The Core Stack Developer Concepts are much more detailed conceptual articles intended for developers who plan modify or contribute to the ROS 2 core:
+
+.. toctree::
+  :maxdepth: 2
 
-See https://docs.ros2.org/ for more high-level ROS 2 documentation.
+  Concepts/About-Build-System
+  Concepts/About-Internal-Interfaces
+  Concepts/About-Middleware-Implementations
+  Concepts/About-Client-Interfaces
 
-Overview of ROS 2 Concepts
---------------------------
+Quick overview of ROS 2 Concepts
+--------------------------------
 
-.. contents:: Table of Contents
+.. contents::
    :local:
 
 ROS 2 is a middleware based on an anonymous publish/subscribe mechanism that allows for message passing between different ROS processes.
 
 At the heart of any ROS 2 system is the ROS graph.
 The ROS graph refers to the network of nodes in a ROS system and the connections between them by which they communicate.
 
-Quick Overview of Graph Concepts
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+Graph Concepts
+^^^^^^^^^^^^^^
 
 
 * Nodes: A node is an entity that uses ROS to communicate with other nodes.

source/Concepts/About-Build-System.rst

@@ -0,0 +1,135 @@
+About the build system
+======================
+
+.. include:: ../../global_substitutions.txt
+
+Under everything is the build system.
+Iterating on ``catkin`` from ROS 1 we have created a set of |packages| under the moniker ``ament``.
+Some of the reasons for changing the name to ``ament`` are that we wanted it to not collide with ``catkin`` (in case we want mix them at some point) and to prevent confusion with existing ``catkin`` documentation.
+``ament``'s primary responsibility is to make it easier to develop and maintain ROS 2 core |packages|.
+However, this responsibility extends to any user who is willing to make use of our build system conventions and tools.
+Additionally it should make |packages| conventional, such that developers should be able to pick up any ``ament`` based |package| and make some assumptions about how it works, how to introspect it, and how to build or use it.
+
+``ament`` consists of a few important repositories which are all in the ``ament`` |GitHub|_ organization:
+
+.. contents::
+   :depth: 1
+   :local:
+
+The ``ament_package`` Package
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Located on |GitHub|_ at `ament/ament_package <https://github.com/ament/ament_package>`_, this repository contains a single :term:`ament Python package` that provides various utilities for |ament packages|, e.g. templates for environment hooks.
+
+All |ament packages| must contain a single :term:`package.xml` file at the root of the package regardless of their underlying build system.
+The :term:`package.xml` "manifest" file contains information that is required in order to process and operate on a |package|.
+This |package| information includes things like the |package|'s name, which is globally unique, and the package's dependencies.
+The :term:`package.xml` file also serves as the marker file which indicates the location of the |package| on the file system.
+
+Parsing of the :term:`package.xml` files is provided by ``catkin_pkg`` (as in ROS 1), while functionality to locate |packages| by searching the file system for these :term:`package.xml` files is provided by build tools such as ``colcon``.
+
+.. glossary::
+
+   package.xml
+       Package manifest file which marks the root of a :term:`package` and contains meta information about the :term:`package` including its name, version, description, maintainer, license, dependencies, and more.
+       The contents of the manifest are in machine readable XML format and the contents are described in the |REPs| `127 <http://www.ros.org/reps/rep-0127.html>`_ and `140 <http://www.ros.org/reps/rep-0140.html>`_, with the possibility of further modifications in future |REPs|.
+
+So anytime some |package| is referred to as an :term:`ament package`, it means that it is a single unit of software (source code, build files, tests, documentation, and other resources) which is described using a :term:`package.xml` manifest file.
+
+.. glossary::
+
+   ament package
+       Any |package| which contains a :term:`package.xml` and follows the packaging guidelines of ``ament``, regardless of the underlying build system.
+
+Since the term :term:`ament package` is build system agnostic, there can be different kinds of |ament packages|, e.g. :term:`ament CMake package`, :term:`ament Python package`, etc.
+
+Here is a list of common package types that you might run into in this software stack:
+
+.. glossary::
+
+    CMake package
+        Any |package| containing a plain CMake project and a :term:`package.xml` manifest file.
+
+    ament CMake package
+        A :term:`CMake package` that also follows the ``ament`` packaging guidelines.
+
+    Python package
+        Any |package| containing a `setuptools <http://pythonhosted.org/setuptools/>`_ based Python project and a :term:`package.xml` manifest file.
+
+    ament Python package
+        A :term:`Python package` that also follows the ``ament`` packaging guidelines.
+
+The ``ament_cmake`` Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Located on |GitHub|_ at `ament/ament_cmake <https://github.com/ament/ament_cmake>`_, this repository contains many "ament CMake" and pure CMake packages which provide the infrastructure in CMake that is required to create "ament CMake" packages.
+In this context "ament CMake" packages means: ``ament`` packages that are built using CMake.
+So the |packages| in this repository provide the necessary CMake functions/macros and CMake Modules to facilitate creating more "ament CMake" (or ``ament_cmake``) packages.
+Packages of this type are identified with the ``<build_type>ament_cmake</build_type>`` tag in the ``<export>`` tag of the :term:`package.xml` file.
+
+The |packages| in this repository are extremely modular, but there is a single "bottleneck" |package| called ``ament_cmake``.
+Anyone can depend on the ``ament_cmake`` |package| to get all of the aggregate functionality of the |packages| in this repository.
+Here a list of the |packages| in the repository along with a short description:
+
+-  ``ament_cmake``
+
+   - aggregates all other |packages| in this repository, users need only to depend on this.
+
+-  ``ament_cmake_auto``
+
+   - provides convenience CMake functions which automatically handle a lot of the tedious parts of writing a |package|'s ``CMakeLists.txt`` file
+
+-  ``ament_cmake_core``
+
+   - provides all built-in core concepts for ``ament``, e.g. environment hooks, resource indexing, symbolic linking install and others
+
+-  ``ament_cmake_gmock``
+
+   - adds convenience functions for making gmock based unit tests
+
+-  ``ament_cmake_gtest``
+
+   - adds convenience functions for making gtest based automated tests
+
+-  ``ament_cmake_nose``
+
+   - adds convenience functions for making nosetests based python automated tests
+
+-  ``ament_cmake_python``
+
+   - provides CMake functions for |packages| that contain Python code
+
+-  ``ament_cmake_test``
+
+   - aggregates different kinds of tests, e.g. gtest and nosetests, under a single target using `CTest <https://cmake.org/Wiki/CMake/Testing_With_CTest>`_
+
+The ``ament_cmake_core`` |package| contains a lot of the CMake infrastructure that makes it possible to cleanly pass information between |packages| using conventional interfaces.
+This makes the |packages| have more decoupled build interfaces with other |packages|, promoting their reuse and encouraging conventions in the build systems of different |packages|.
+For instance it provides a standard way to pass include directories, libraries, definitions, and dependencies between |packages| so that consumers of this information can access this information in a conventional way.
+
+The ``ament_cmake_core`` |package| also provides features of the ``ament`` build system like symbolic link installation, which allows you to symbolically link files from either the source space or the build space into the install space rather than copying them.
+This allows you to install once and then edit non-generated resources like Python code and configuration files without having to rerun the install step for them to take effect.
+This feature essentially replaces the "devel space" from ``catkin`` because it has most of the advantages with few of the complications or drawbacks.
+
+Another feature provided by ``ament_cmake_core`` is the |package| resource indexing which is a way for |packages| to indicate that they contain a resource of some type.
+The design of this feature makes it much more efficient to answer simple questions like what |packages| are in this prefix (e.g. ``/usr/local``) because it only requires that you list the files in a single possible location under that prefix.
+You can read more about this feature in the `design docs <https://github.com/ament/ament_cmake/blob/master/ament_cmake_core/doc/resource_index.md>`_ for the resource index.
+
+Like ``catkin``, ``ament_cmake_core`` also provides environment setup files and |package| specific environment hooks.
+The environment setup files, often named something like ``setup.bash``, are a place for |package| developers to define changes to the environment that are needed to utilize their |package|.
+The developers are able to do this using an "environment hook" which is basically an arbitrary bit of shell code that can set or modify environment variables, define shell functions, setup auto-completion rules, etc...
+This feature is how, for example, ROS 1 set the ``ROS_DISTRO`` environment variable without ``catkin`` knowing anything about the ROS distribution.
+
+The ``ament_lint`` Repository
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Located on |GitHub|_ at `ament/ament_lint <https://github.com/ament/ament_lint>`_, this repository provides several |packages| which provide linting and testing services in a convenient and consistent manner.
+Currently there are |packages| to support C++ style linting using ``uncrustify``, static C++ code checks using ``cppcheck``, checking for copyright in source code, Python style linting using ``pep8``, and other things.
+The list of helper packages will likely grow in the future.
+
+Build tools
+~~~~~~~~~~~
+
+A build tool performs the task of building a workspace of packages together at once with a single invocation.
+For ROS 2 releases up to Ardent, the build tool providing this functionality is called ``ament_tools``.
+As of ROS 2 Bouncy, ``ament_tools`` has been superseded by ``colcon``, as described in `the universal build tool article <http://design.ros2.org/articles/build_tool.html>`_.

source/Concepts/About-Client-Interfaces.rst

@@ -0,0 +1,54 @@
+ROS 2 Client Interfaces (Client Libraries)
+==========================================
+
+.. include:: ../../global_substitutions.txt
+
+ROS Client Interfaces, a.k.a. |client libraries|, are user facing interfaces which provide the high level functionality and are built on top of the ``rcl`` and ``rosidl`` |APIs|.
+
+.. rclc is not up-to-date
+    The ``rclc`` Package
+    ~~~~~~~~~~~~~~~~~~~~
+
+    The ROS Client Library for C (``rclc``) is the user facing C idiomatic interface which provides all of the ROS client functionality like creating nodes, publisher, and subscribers.
+    This |API| uses the ``rcl`` |API| and the ``rosidl`` |API| to implement its functions.
+    Because both ``rcl`` and ``rclc`` are written in C, you might wonder what the difference is between the two |APIs|.
+    The ``rcl`` |API| provides functions for things like creating nodes, publishers, and subscribers, which are exposed through to the ``rclc`` |API|, but the ``rclc`` |API| additionally handles things like the threading model, configuration, and other components of the client library which are solved differently in different languages.
+    Since ``rcl`` and ``rclc`` are so similar to each other, ``rclc`` essential can be described as ``rcl`` plus execution (threading).
+    However, the distinction becomes clearer when you consider client libraries in different languages.
+
+    The ``rclc`` repository is located on |GitHub|_ at `ros2/rclc <https://github.com/ros2/rclc>`_ and contains the |package| ``rclc`` which contains the development resources, interface and reference implementation that is required at runtime.
+
+    .. warning::
+
+        TODO: Link to the ``rclc`` |API| docs
+
+The ``rclcpp`` Package
+~~~~~~~~~~~~~~~~~~~~~~
+
+The ROS Client Library for C++ (``rclcpp``) is the user facing, C++ idiomatic interface which provides all of the ROS client functionality like creating nodes, publisher, and subscribers.
+``rclcpp`` builds on top of ``rcl`` and the ``rosidl`` |API|, and it is designed to be used with the C++ messages generated by ``rosidl_generator_cpp``.
+
+``rclcpp`` makes use of all the features of C++ and C++11 to make the interface as easy to use as possible, but since it reuses the implementation in ``rcl`` it is able maintain a consistent behavior with the other client libraries that use the ``rcl`` |API|.
+
+The ``rclcpp`` repository is located on |GitHub|_ at `ros2/rclcpp <https://github.com/ros2/rclcpp>`_ and contains the |package| ``rclcpp``.
+The generated |API| documentation is here:
+
+`api/rclcpp/index.html <http://docs.ros2.org/foxy/api/rclcpp/index.html>`_
+
+The ``rclpy`` Package
+~~~~~~~~~~~~~~~~~~~~~
+
+The ROS Client Library for Python (``rclpy``) is the Python counterpart to the C++ client library.
+Like the C++ client library, ``rclpy`` also builds on top of the ``rcl`` C API for its implementation.
+The interface provides an idiomatic Python experience which uses native Python types and patterns like lists and context objects, but by using the ``rcl`` |API| in the implementation it stays consistent with the other client libraries in terms of feature parity and behavior.
+In addition to providing Python idiomatic bindings around the ``rcl`` |API| and Python classes for each message, the Python client library takes care of the execution model, using ``threading.Thread`` or similar to run the functions in the ``rcl`` |API|.
+
+Like C++ it generates custom Python code for each ROS message that the user interacts with, but unlike C++ it eventually converts the native Python message object into the C version of the message.
+All operations happen on the Python version of the messages until they need to be passed into the ``rcl`` layer, at which point they are converted into the plain C version of the message so it can be passed into the ``rcl`` C |API|.
+This is avoided if possible when communicating between publishers and subscribers in the same process to cut down on the conversion into and out of Python.
+
+The ``rclpy`` repository is located on |GitHub|_ at `ros2/rclpy <https://github.com/ros2/rclpy>`_ and contains the |package| ``rclpy``.
+The generated |API| documentation is here:
+
+
+`api/rclpy/index.html <http://docs.ros2.org/foxy/api/rclpy/index.html>`_