Merge pull request #58 from fsfeup-driverless/dev

Release 0

.gitattributes

@@ -0,0 +1,4 @@
+*.html linguist-vendored
+*.css linguist-vendored
+*.js linguist-vendored 
+*.tex linguist-vendored

.github/workflows/test.yml → .github/workflows/build.yml

@@ -1,4 +1,4 @@
-name: Testing and Validating
+name: Testing and Building
 
 on:
   push:
@@ -7,17 +7,6 @@ on:
     branches: [ "main" ]
 
 jobs:
-  cppcheck:
-    runs-on: ubuntu-latest
-
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Install cppcheck
-        run: sudo apt install cppcheck
-
-      - name: Run cppcheck
-        run: cppcheck --enable=all --error-exitcode=1 src/ -i test/
 
   build:
     runs-on: ubuntu-20.04
@@ -70,7 +59,8 @@ jobs:
       - name: Compile and Test Localization and Mapping
         run: |
           source /opt/ros/galactic/setup.bash
-          cd ./src/localization-mapping/
-          colcon build
+          cd ./src/
+          ros2 interface list
+          colcon build --packages-select custom_interfaces loc_map
           source install/setup.bash
-          colcon test --event-handler=console_direct+
+          colcon test --packages-select loc_map --event-handler=console_direct+

.github/workflows/static-analysis.yml

@@ -0,0 +1,32 @@
+name: Static Analysis
+
+on:
+  push:
+    branches: [ "main", "dev" ]
+  pull_request:
+    branches: [ "main", "dev" ]
+
+jobs:
+  cppcheck:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install cppcheck
+        run: sudo apt install cppcheck
+
+      - name: Run cppcheck
+        run: cppcheck --enable=all --error-exitcode=1 src/ -i test/
+
+  cpplint:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v3
+
+      - name: Install cpplint
+        run: pip install cpplint
+
+      - name: Run cpplint
+        run: cpplint --recursive ./src/

.gitignore

@@ -1,3 +1,6 @@
 **/.vscode/*
 **/.idea/*
-**/.DS_Store
+**/.DS_Store
+**/build/*
+**/install/*
+**/log/*

docs/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Change Log
+
+All notable changes to this project will be documented in this file.
+
+## Sprint 2
+
+### Localization and Mapping
+- Localization and Mapping publisher node
+- Cone, ConeArray and Pose messages
+
+## Sprint 1
+
+### Control
+
+- The pre-existing PID algorithm was integrated into a ROS Node
+- A path-planning mock publisher was created so that the control node could receive test messages
+- A custom interfaces package was built to support any custom messages in the project

docs/README.md

@@ -4,7 +4,7 @@ This folder contains most of the documentation of the project.
 
 ## Tutorials
 
-There are many tutorials in this project in the [tutotials directory](./tutorials). There is also a [Startup Guide](./tutorials/startup_guide.md) suggesting some tutorials and the order in which they should be read/tried.
+There are many tutorials in this project in the [tutorials directory](./tutorials). There is also a [Startup Guide](./tutorials/startup_guide.md) suggesting some tutorials and the order in which they should be read/tried.
 
 ## Other documentation
 

docs/assets/environment_setup_tutorial/Doxyfile.example

@@ -1295,7 +1295,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = YES
+GENERATE_HTML          = NO
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

docs/assets/environment_setup_tutorial/training/Doxyfile

@@ -1295,7 +1295,7 @@ IGNORE_PREFIX          =
 # If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
 # The default value is: YES.
 
-GENERATE_HTML          = YES
+GENERATE_HTML          = NO
 
 # The HTML_OUTPUT tag is used to specify where the HTML docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of
@@ -1933,7 +1933,7 @@ EXTRA_SEARCH_MAPPINGS  =
 # If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
 # The default value is: YES.
 
-GENERATE_LATEX         = NO
+GENERATE_LATEX         = YES
 
 # The LATEX_OUTPUT tag is used to specify where the LaTeX docs will be put. If a
 # relative path is entered the value of OUTPUT_DIRECTORY will be put in front of

docs/assets/environment_setup_tutorial/training/document.sh

@@ -0,0 +1,8 @@
+# This script requires a Doxyfile to be in the current directory, as well as pdflatex to be installed with its dependencies. 
+# Refer to https://gist.github.com/rain1024/98dd5e2c6c8c28f9ea9d to install pdflatex
+sudo rm -rf ./doxygen
+doxygen
+cd doxygen/latex
+make
+cd ..
+mv latex/refman.pdf ./documentation.pdf

docs/assets/environment_setup_tutorial/training/experiment1/CMakeLists.txt

@@ -11,9 +11,9 @@ find_package(ament_cmake REQUIRED)
 # further dependencies manually.
 # find_package(<dependency> REQUIRED)
 
-add_executable(node1 src/node1.cpp src/car.cpp)
+add_executable(${PROJECT_NAME} src/node1.cpp src/car.cpp)
 
-target_include_directories(node1 PUBLIC
+target_include_directories(${PROJECT_NAME} PUBLIC
   $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
   $<INSTALL_INTERFACE:include>)
 target_compile_features(node1 PUBLIC c_std_99 cxx_std_17)  # Require C99 and C++17
@@ -37,7 +37,7 @@ if(BUILD_TESTING)
     )
 
   ament_add_gtest(${PROJECT_NAME}_test ${TESTFILES})
-  target_include_directories(node1 PUBLIC
+  target_include_directories(${PROJECT_NAME}_test PUBLIC
     $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
     $<INSTALL_INTERFACE:include>)
 

docs/tutorials/starting_to_code.md → docs/tutorials/coding_environment.md

@@ -1,4 +1,4 @@
-# Starting to code
+# Coding environment
 
 This tutorial aims to aid in teaching the developer how to use multiple tools established for this project, as well as creating a base ROS package.
 
@@ -7,6 +7,10 @@ This tutorial aims to aid in teaching the developer how to use multiple tools es
 - [SSH to Virtual Machine](https://averagelinuxuser.com/ssh-into-virtualbox/)
 - [VSCode](https://code.visualstudio.com/Download)
 
+## Project Structure
+
+This project is divided into multiple folders inside **src** folder. Each of these folders contain a ROS2 package. Essentially, the project is composed of multiple ROS2 packages whose nodes interact with each other in runtime. More details on the system's architecture can be found in [here](../project-specification.md). 
+
 ## IDE
 
 In order to properly contribute to this project, a code editor or IDE is suggested. In this tutorial, a suggestion for an environment will be presented.
@@ -30,26 +34,6 @@ As the simulator required specific versions of Ubuntu to function, the setup cho
     - CMake extension 
     - C++ Intellisense extension
 
-## Doxygen
-
-In order to help future developers start contributing to this project, code should be easy to read and staightforward. However, this is easier said than done. For this reason, it is helpful to use a documentation tool to document the code developed. Doxygen is the de-fact tool for documentation in C++. To use it you should:
-- [Install doxygen](https://www.doxygen.nl/download.html) in your machine (virtual machine in this case)
-    - Download
-    - Follow the compilation and installation instructions in the manual
-- Create doxygen file in the project home directory
-    - Run ```doxygen -g``` on the command line
-    - Edit the file to your liking
-        - Check the INPUT variable, for this is the one that defines what files will be read to generate the documentation
-- Comment the code with doxygen comments
-    - Use [this vscode extension](https://marketplace.visualstudio.com/items?itemName=cschlosser.doxdocgen) for automatic doxygen documentation generation
-- Run ```doxygen``` on the root directory to generate documentation
-
-There is an example doxyfile [here](../assets/environment_setup_tutorial/Doxyfile.example)
-
-## CPPCheck
-
-In this project, we will be using CPPCheck as a static analysis tool, to check for any underlying bugs. We will be using it in the Gitlab pipeline, but it is handy that the developer can use it locally. To install it, in the Virtual Machine, just run ```sudo apt install cppcheck```
-To use it, run ```cppcheck --enable=all --error-exitcode=1 src/ -i test/```. This command already has some tunning to ignore some things and not ignore others. To learn more, run ```cppcheck -h```.
 
 ## File Strucure and Guidelines
 

docs/tutorials/documentation.md

@@ -0,0 +1,99 @@
+# Documenting Work
+
+In order to pass down the knowledge aquired to the next generations of driverless engineers and to make the code developed easier to understand, it is fundamental that both the code, system design and architecture and decisions are all documented.
+
+- For code documentation, we will be using **Doxygen**. 
+- To document the current structure of the system, the **documentation section** of this repository will be used. 
+- To further document design decisions of the system and the whole theoretical analysis behind our decisions, **overleaf** latex documents will be used.
+
+## Doxygen Setup
+
+In order to help future developers start contributing to this project, code should be easy to read and staightforward. However, this is easier said than done. For this reason, it is helpful to use a documentation tool to document the code developed. Doxygen is the de-fact tool for documentation in C++. To use it you should:
+- [Install doxygen](https://www.doxygen.nl/download.html) in your machine (virtual machine in this case)
+    - Download
+    - Follow the compilation and installation instructions in the manual
+- Create doxygen file in the project home directory
+    - Run ```doxygen -g``` on the command line
+    - Edit the file to your liking
+        - Check the INPUT variable, for this is the one that defines what files will be read to generate the documentation
+- Comment the code with doxygen comments
+    - Use [this vscode extension](https://marketplace.visualstudio.com/items?itemName=cschlosser.doxdocgen) for automatic doxygen documentation generation
+- Run ```doxygen``` on the root directory to generate documentation
+
+There is an example doxyfile [here](../assets/environment_setup_tutorial/Doxyfile.example). This doxyfile is configured to generate only latex documentation (as oposed to latex + html).
+
+The [example project](../assets/environment_setup_tutorial/training/) also contains a Doxyfile (it is the same as the one mentioned above) and a [script](../assets/environment_setup_tutorial/training/document.sh) that generates a pdf file + the latex output from doxygen. This script required the installation of [pdflatex](https://gist.github.com/rain1024/98dd5e2c6c8c28f9ea9d). The example project also contains commented code.
+
+## Doxygen Python
+
+After following the [Doxygen Setup guide](#doxygen-setup), you need to make a few changes to the default *Doxyfile* so that the Doxygen command correctly parses python code:
+
+- Enable `JAVADOC_AUTOBRIEF`, changing its value from `NO` to `YES`. This allows Doxygen to utilize Javadoc style briefs which look something like this:
+
+```py
+##
+# Brief summary description of the particular element.
+#
+# Detailed description of the particular element
+# that includes much more information.
+```
+
+- To optimize the generated documentation for Java and Python based source code, change the `OPTIMIZE_OUTPUT_JAVA` to `YES`.
+
+- Tell Doxygen to generally extract all elements found in the source code, `EXTRACT_ALL` to `Yes`.
+
+   - Note, the `EXTRACT_PRIVATE` and `EXTRACT_STATIC` settings can also be set to `YES` if you want to include private class members and static file members in the generated documentation as well.
+
+- Activate `HIDE_SCOPE_NAMES` to `YES`, hiding the scope name that is typically prepended to element names contained within that scope.
+
+- To sort the elements in alphabetical order instead of when they are declared, set `SORT_BRIEF_DOCS` to `YES`.
+
+These are just some enhancements to the extraction and readability of the generated documentation. In reality, only `OPTIMIZE_OUTPUT_JAVA` and `INPUT` are required.
+
+Supposing you have already changed the `INPUT` to find the Python source code, you are all set to start generating Python documentation with Doxygen.
+
+### Comment blocks in Python
+
+For Python there is a standard way of documenting the code using so called documentation strings `"""`. However when using these strings none of doxygen's special commands are supported and the text is shown as verbatim text.
+
+To have the doxygen's special commands and have the text as regular documentation instead of `"""` use `"""!` or set `PYTHON_DOCSTRING` to `NO` in the configuration file.
+
+```py
+"""!
+@package docstring
+Documentation for this module.
+ 
+More details.
+"""
+
+def func():
+    """!
+    Documentation for a function.
+ 
+    More details.
+    """
+    pass
+
+class PyClass:
+    """!
+    Documentation for a class.
+ 
+    More details.
+    """
+
+    def __init__(self):
+        """!
+        The constructor.
+        
+        @param self Param documentation
+        """
+        self._memVar = 0
+
+    def PyMethod(self):
+        """!
+        Documentation for a method.
+        
+        @return The return value
+        """
+        pass
+```