Ament lint documentation

docs/_09_development/_develop_guide/_develop_guide/_develop_new_pkg.rst

@@ -0,0 +1,320 @@
+.. _development_guide_new_pkg:
+
+------------------------
+Developing a New Package
+------------------------
+
+TDB
+
+
+
+.. _development_guide_new_pkg_architecture:
+
+Architecture of a New Package
+=============================
+
+Every new package should have the following architecture:
+
+.. code-block::
+
+    /package_name
+    /include
+        /package_name
+        header_files(.hpp)
+    /launch
+    /src
+        implementation_files(.cpp)
+        main_files(.cpp)
+    /tests
+        CMakeLists.txt
+        test_files(.cpp)
+    CmakeLists.txt
+    package.xml
+    Readme.md
+    .gitignore
+
+
+
+.. _development_guide_new_pkg_code_style:
+
+Code Style
+==========
+
+Aerostack2 follows the `ROS 2 code style and language versions <https://docs.ros.org/en/humble/The-ROS2-Project/Contributing/Code-Style-Language-Versions.html>`_.
+
+
+
+.. _development_guide_new_pkg_code_style_c++:
+
+C++
+---
+
+Code should follows the `google c++ style guide <https://google.github.io/styleguide/cppguide.html>`_.
+
+Every file should start with the Licence text, which looks like this:
+
+.. code-block:: c++
+
+    /*********************************************************************************************
+    *  \file       [file name]
+    *  \brief      [brief description of the file]
+    *  \authors    [name of the author]
+    *  \copyright  Copyright (c) 2021 Universidad Politécnica de Madrid
+    *              All Rights Reserved
+    *
+    * Redistribution and use in source and binary forms, with or without
+    * modification, are permitted provided that the following conditions are met:
+    * 
+    * 1. Redistributions of source code must retain the above copyright notice,
+    *    this list of conditions and the following disclaimer.
+    * 2. Redistributions in binary form must reproduce the above copyright notice,
+    *    this list of conditions and the following disclaimer in the documentation
+    *    and/or other materials provided with the distribution.
+    * 3. Neither the name of the copyright holder nor the names of its contributors
+    *    may be used to endorse or promote products derived from this software
+    *    without specific prior written permission.
+    * 
+    * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+    * "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+    * THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+    * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+    * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+    * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+    * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+    * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+    * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+    * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+    * EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+    **********************************************************************************************/
+
+Documentation will be generate using `Doxygen <https://www.doxygen.nl/manual/docblocks.html>`_.
+Therefore, header files should include a comment over every definition in order to generate the documentation properly.
+The comments made in the current nodes are writing using Javadoc style.
+
+Please, do not use std::cout or similar functions to show messages in command line. Instead, use logging macros like RCLCPP_INFO from ROS logging library.
+
+
+
+.. _development_guide_new_pkg_code_style_python:
+
+Python
+------
+
+Code should follow the `PEP 8 <https://peps.python.org/pep-0008/>`_ and `PEP 257 <https://peps.python.org/pep-0257/>`_ guidelines.
+
+.. _development_guide_new_pkg_test:
+
+Test
+====
+
+To be used in Aerostack2, every package must pass, at least, the Code Style tests. Additional functional tests might be added to a package to provide a validation of its functionalities.
+
+
+.. _development_guide_new_pkg_test_style:
+
+Code Style Test
+---------------
+
+Aerostack2 uses `ament_lint <https://github.com/ament/ament_lint>`_ to perform style checks over the packages files.
+
+For configuring style tests, this must be added on the ``CMakeList.txt`` of your package:
+
+.. code-block:: cmake
+
+    if(BUILD_TESTING)
+
+    find_package(ament_lint_auto REQUIRED)
+    ament_lint_auto_find_test_dependencies()
+
+    endif()
+
+Also, these packages must be added to the ``package.xml``
+
+.. code-block::
+
+    <test_depend>ament_lint_auto</test_depend>
+    <test_depend>ament_lint_common</test_depend>
+
+The tests that are performed as part of ament_lint_common can be found `here <https://github.com/ament/ament_lint/blob/humble/ament_lint_common/doc/index.rst>`_.
+
+Some test dependencies are also required and can be installed by running:
+
+.. code-block:: bash
+
+    apt-get install python3-rosdep python3-pip python3-colcon-common-extensions python3-colcon-mixin ros-dev-tools -y
+    apt-get install python3-flake8-builtins python3-flake8-comprehensions python3-flake8-docstrings python3-flake8-import-order python3-flake8-quotes -y
+
+The package can now be compiled running:
+
+.. code-block:: bash
+
+    as2 build <package_name>
+
+And to run the tests, execute:
+
+.. code-block:: bash
+
+    as2 test -v <package_name>
+
+The ``-v`` flag will print all the details of the test run, including information about the tests that did not pass and the specific erros that occurred.
+
+.. _development_guide_new_pkg_test_style_CLI:
+
+Running Individual Tests on CLI
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Ament_lint includes a series of CLI commands with which the tests can be run separately. This might be helpful for fixing the package and eliminate the errors.
+These CLI tools can be found on the folder of the specific test on the `ament_lint repository <https://github.com/ament/ament_lint>`_.
+
+· Running and Passing 'ament_uncrustify'
+""""""""""""""""""""""""""""""""""""""""""
+
+The test ``ament_uncrustify`` can be launched by running:
+
+.. code-block:: bash
+
+    ament_uncrustify --reformat <path/to/package/directory>/*
+
+Or simply by running the next command from the directory of your package:
+
+.. code-block:: bash
+
+    ament_uncrustify --reformat
+
+Either way, the ``--reformat`` flag will automatically reformat the files in which erros have been found, apart from notifying which are these files.
+
+· Running and Passing 'ament_copyright'
+""""""""""""""""""""""""""""""""""""""""""
+
+The test ``ament_copyright`` can be launched by running the next command from your package directory:
+
+.. code-block:: bash
+
+    ament_copyright --add-missing "Universidad Politécnica de Madrid" bsd_3clause
+
+The flag ``--add-missing`` will add the Licence text to all the files that do not include one.
+
+· Running and Passing 'ament_pep257'
+""""""""""""""""""""""""""""""""""""""
+
+The test ``ament_pep257`` can be launched by running the next command from your package directory:
+
+.. code-block:: bash
+
+    ament_pep257
+
+The third-party autoformatter `docformatter <https://github.com/PyCQA/docformatter>`_ can be used to help passing this test. It can be installed executing
+
+.. code-block:: bash
+
+    pip install --upgrade docformatter
+
+and launched over the ``.py`` files by running:
+
+.. code-block:: bash
+
+    for file in $(find <path/to/package/directory> -name "*.py"); do
+        python-lint "$file"
+    done
+
+This may NOT fix all the errors, but it will eliminate some of them.
+
+· Running and Passing 'ament_cppcheck'
+""""""""""""""""""""""""""""""""""""""""
+
+The test ``ament_cppcheck`` can be launched by running the next command from your package directory:
+
+.. code-block:: bash
+
+    ament_cppcheck
+
+You may encounter the following error when running the test alone:
+
+.. code-block:: bash
+
+    cppcheck 2.7 has known performance issues and therefore will not be used, set the AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS environment variable to override this.
+
+This can be fixed by setting the ``AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS`` to whatever that evaluates to 'True', just as the error message indicates:
+
+.. code-block:: bash
+
+    export AMENT_CPPCHECK_ALLOW_SLOW_VERSIONS=true
+
+
+.. _development_guide_new_pkg_test_functional:
+
+Code Functional Test
+--------------------
+
+In aerostack2 we use googletest (GTest) library to perform unit tests across the packages.
+GTest complete documentation about how to write your own unit tests can be found at:
+https://github.com/google/googletest
+
+In order to compile this tests some lines must be added into a **NEW** ``CMakeLists.txt`` file located in a ``tests/`` folder.
+
+.. code-block:: cmake
+
+    # Add gtest dependencies and install them if they are not already installed
+
+    find_package(gtest QUIET)
+    if (${Gtest_FOUND})
+    MESSAGE(STATUS "Found Gtest.")
+    else (${Gtest_FOUND})
+    MESSAGE(STATUS "Could not locate Gtest.")
+    include(FetchContent)
+    FetchContent_Declare(
+        googletest
+        URL https://github.com/google/googletest/archive/609281088cfefc76f9d0ce82e1ff6c30cc3591e5.zip
+    )
+    # For Windows: Prevent overriding the parent project's compiler/linker settings
+    set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
+    FetchContent_MakeAvailable(googletest)
+
+    endif(${Gtest_FOUND})
+
+    include(GoogleTest)
+
+    enable_testing()
+    # find all *.cpp files in the tests directory
+
+    file(GLOB TEST_SOURCES tests/*.cpp )
+
+    # create a test executable for each test file
+    foreach(TEST_SOURCE ${TEST_SOURCES})
+
+    get_filename_component(_src_filename ${TEST_SOURCE} NAME)
+    string(LENGTH ${_src_filename} name_length)
+    math(EXPR final_length  "${name_length}-4") # remove .cpp of the name
+    string(SUBSTRING ${_src_filename} 0 ${final_length} TEST_NAME)
+
+    add_executable(${TEST_NAME}_test ${TEST_SOURCE})
+    ament_target_dependencies(${TEST_NAME}_test  ${PROJECT_DEPENDENCIES})
+    target_link_libraries(${TEST_NAME}_test gtest_main ${PROJECT_NAME})
+
+    # add the test executable to the list of executables to build
+    gtest_discover_tests(${TEST_NAME}_test)
+
+    endforeach()
+
+In order to link this ``./tests/CMakeLists.txt`` file into the ``CMakeLists.txt`` file of the package, the following line must be added:
+
+.. code-block:: cmake
+
+    if(BUILD_TESTING)
+    # all the other tests
+    include(./tests/CMakeLists.txt)
+    endif()
+
+
+To run these tests:
+
+.. code-block:: bash
+
+    $ colcon test 
+
+.. _development_guide_new_pkg_test_coverage:
+
+Code Coverage Test
+------------------
+
+TDB