Merge pull request #8 from ipa320/rst

Migration to rst format

README.rst

@@ -0,0 +1,98 @@
+RosTooling
+==========
+
+Welcome to the RosTooling documentation page! :)
+
+The RosTooling aims to bridge the advantages of ROS with those of model-driven software development. At its core are a set of models that describe "every day" code developed by ROS developers, both at the component and system levels. These models are supported with different types of tools including model extractors from code, validators, and code generators.
+
+We invite you to take a look at the tutorials to learn more about this tooling and its uses.
+
+The `source code <https://github.com/ipa320/RosTooling>`_ of the entire implementation of the tooling is completely open-source. Contributions, feedback, and suggestions are always welcome.
+
+Installation
+------------
+
+- `From Release <docu/Installation.rst#option-1-using-the-release-version-recommended>`_
+- `Setup <docu/Environment_setup.rst#1-switch-to-the-ros-developer-perspective>`_
+
+Models Review
+-------------
+
+The RosTooling divides the ROS concepts into three layers of models:
+
+- **Ros objects models**: They represent the interface types. In ROS world, these are the message, services, and action types. This file has the `.ros` extension and allows a YAML format similar to the ROS `.msgs`, `.srvs`, and `.action` files.
+- **Ros packages (component) models**: They represent the filesystem level of ROS packages, as well as the computational graph. In other words, the package description, the implemented artifacts, and the communication ports the nodes offer. They have two different implementations, for ROS (1) (`.ros1` extension) or for ROS 2 (`.ros2` extension files.)
+- **Ros System models**: They represent the ROS nodes as components present in a system and the connections among them. The file extension of this type of model is `.rossystem`.
+
+Components (.ros1, .ros2)
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- `How to describe ROS nodes using models <docu/RosModelDescription.rst>`_
+- `Parameters API reference and examples <docu/ParametersAPI.rst>`_
+
+Communication objects (.ros)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+- `Messages, services and actions generator <docu/NewCommunicationObjects.rst>`_
+
+Systems (.rossystem)
+~~~~~~~~~~~~~~~~~~~~
+
+- `How to describe ROS systems using model <docu/RosSystemModelDescription.rst>`_
+
+Tutorials
+---------
+
+.. image:: docu/images/Attention.png
+   :alt: Attention
+
+All tutorials were created on Linux. In addition, some of them require a local installation of ROS 2, which are marked with the logo:
+
+.. image:: docu/images/Ros2_logo_mini.png
+   :alt: ROS 2 logo
+
+The modeling part should run on other OS as long as Eclipse is properly installed and also the required Java packages (JRE and JDK). The current version of the RosTooling requires Java 19 or higher.
+
+In case you have already installed the RosTooling, we recommend always pulling the latest version. Go to "Help" -> "Check for Updates", and in case a new version is available, it will be proposed to be updated.
+
+If you encounter issues during the execution of these tutorials, please report them under the following `GitHub Issues <https://github.com/ipa320/RosTooling.github.io/issues/new?assignees=&labels=&projects=&template=bug_report.md&title=>`_. If you don't have a GitHub account, please just send an email to [email protected].
+
+Also, we would be very thankful if once you complete the tutorials, you take 15 minutes to fill out our survey. This will help us to improve our solution: `Survey link <https://forms.office.com/e/2V5pPwcY7V>`_.
+
+Many thanks for your help :)
+
+Components
+~~~~~~~~~~
+
+- `Review models and use of textual editor <docu/LearnRosModels.rst>`_
+- (Optional) `Create your own model <docu/CreateYourModel.rst>`_
+- `Generate code from model description <docu/rossdl.rst>`_ .. image:: docu/images/Ros2_logo_mini.png
+- `Extract models using static code analysis <docu/StaticCodeAnalyis.rst>`_ .. image:: docu/images/docker_logo.png
+- `Extract component models using introspection at runtime <docu/ros2model.rst>`_ .. image:: docu/images/Ros2_logo_mini.png
+
+Systems
+~~~~~~~
+
+- `Review models and use of textual editor <docu/LearnRosSystemModels.rst>`_
+- `Other ways to define a system <docu/LearnRosSystemModels2.rst>`_
+- `Code generator review <docu/CodeGeneration.rst>`_
+- `System Models visualization <docu/SystemModelsVisualization.rst>`_
+- Real use cases execution:
+
+  - `Turtlesim <docu/Example_Turtlesim.rst>`_
+
+  - `Beginner - Mobile base on simulation <docu/MobileBase_beginner.rst>`_
+
+  - `TBD - Advanced - Manipulation <docu/Manipulation_advanced.rst>`_
+
+.. |ros2| image:: docu/images/Ros2_logo_mini.png
+   :alt: ROS2 logo
+   :scale: 100%
+   :background: white
+
+Extra material
+--------------
+
+- `Eclipse known issues <docu/eclipse_issues.rst>`_
+- `RosTooling Known issues <docu/RosTooling_issues.rst>`_
+- `Create your own model from nodes <docu/Example_PubSub.rst>`_

docu/CodeGeneration.rst

@@ -0,0 +1,24 @@
+Systems code generator review
+=============================
+
+For the System model, the generation of code is automatic. This means if your model is correct and follows the connection rules, Xtext will automatically generate a ROS package into the *src-gen* folder, which has the typical structure of a Python package meant to hold launch file artifacts. More concretely:
+
+- **README file**: This file will always be generated, even in cases of a system that only points to an existing launch file. The README contains information about the design of the system, as well as how to install the dependencies, set up the workspace to hold the created implementation, and start the generated artifact.
+
+- **setup.py script**: This is the standard script required for a Python package, specifically created for the structure of this package.
+
+- **package.xml file**: A template for the `package.xml` of the package, which contains the specification of all the required dependencies to start the package. The user should complete the type of license, maintainer, owner, and description of the package.
+
+- **CMakeLists.txt**: A template of the `package.xml`, which includes the required tags to install the newly created files.
+
+- **launch/NameOfTheSystem.launch.py script**: This is the core of the generator. It is a **ready-to-execute** file based on the `.rossystem` description:
+  - Add includes for all the defined nodes as components
+  - Define and set the values of the parameters. For packages containing more than 5 parameters, the `.yaml` file under the "config" folder will be loaded and launched.
+  - Remap topics to force connections (only working for nodes that are part of the system as components, not for subsystems). See `known issues <RosTooling_issues.rst#code-generators>`_.
+  - Include other launch files from subsystems.
+
+- **resource/NameOfTheSystem.puml**: `An example of a PlantUML implementation of the described system <SystemModelsVisualization.rst#open-the-plantuml-auto-generated-description>`_.
+
+- **config/NameOfTheSystem.yaml**: This file contains the configuration of the parameters. It will only be used if there are 5 or more parameters.
+
+With the current implementation of RosTooling, adding new code generators to the `.rossystem` representation is very easy. Please report on our survey's open-ended questions regarding your wishes, such as the generation of install scripts, Docker container configuration, or ROS1-ROS2 bridges.

docu/CreateYourModel.rst

@@ -0,0 +1,8 @@
+Create your model
+=================
+
+You can create a new file with the extension `.ros2` in the `rosnodes` folder from the previously created `project <LearnRosModels.rst>`_ by right-clicking on the folder and selecting **New -> File**.
+
+This will create an empty file where you can create your model. As a helper, you can use the `reference documentation <RosModelDescription.rst>`_ and press **Ctrl + Space** to use the auto-complete functionality.
+
+If auto-complete or the grammar highlighting is not working, check that the file is opened with the "Ros 2 Editor" by right-clicking on the file and selecting **Open with...**.

docu/Environment_setup.rst

@@ -0,0 +1,35 @@
+Setup the environment and start the Eclipse application
+=======================================================
+
+Switch to the ROS Developer perspective
+---------------------------------------
+
+Go to Menu *Window* -> *Perspective* -> *Open Perspective* -> *Other...* -> *ROS developer*. Your application toolbar will be automatically configured.
+
+Import the common communication objects project
+-----------------------------------------------
+
+Import the project located under the "ROSCommonObjects" folder of this repository to the workbench of your application:
+
+.. code-block:: none
+
+   de.fraunhofer.ipa.ros.communication.objects
+
+If you have an internet connection, you can use the button that clones the objects from GitHub into your workspace and imports them automatically:
+
+.. image:: images/clone_and_import.png
+
+.. image:: images/Attention.png
+
+This button will only work on Linux machines. Alternatively, you can manually clone the `repository <https://github.com/ipa320/RosCommonObjects>`_ and import the project by navigating to *File* -> *Import* -> *General* -> *Existing Projects into Workspace*. 
+Then select the container folder of the cloned repository.
+
+Import the catalog
+------------------
+
+You can also download and import a pre-existing catalog of examples. The catalog is publicly available on GitHub: `ipa-nhg/RosModelsCatalog <https://github.com/ipa-nhg/RosModelsCatalog>`_.
+
+Please clone the repository and import it into your Eclipse workspace. This can be easily done by navigating to *File* -> *Import* -> *General* -> *Existing Projects into Workspace*. 
+Then select the container folder of the cloned repository.
+
+.. image:: images/01_mobile_base_b.gif