From 5b40d917935a1c66e22f8a5233225a8dd6871f4f Mon Sep 17 00:00:00 2001 From: Murilo Marinho Date: Wed, 28 Oct 2026 13:51:07 +0000 Subject: [PATCH] Docs: group pages into per-topic directories Mirrors the transformations/gazebo/navigation (and cybersecurity/cpp/ sas/docker/cmake) layout for the remaining 24 flat pages, one directory per toctree caption: - setup/: installation, terminator, workspace_setup - packages/: create_packages, create_python_package, create_python_node_with_template, source_after_build, running_node - python_node/: create_python_node_from_scratch, python_node_explained - python_library/: create_python_library, using_python_library - interfaces/: interfaces, create_interface_package - messages/: publishers_and_subscribers, inspecting_topics - parameters_and_launch/: parameters_and_launch, launch_configurable_nodes, inspecting_parameters - services/: service_servers_and_clients, inspecting_services - actions/: actions, action_servers, action_clients index.rst, tools.rst, faq.rst and the two included snippets (the_canonical_build_command, the_topic_is_under_heavy_construction) stay at the source root -- the snippets are included from every depth and the ../the_... convention of the existing topic dirs applies. Relative paths (literalinclude/:download: ../.. -> ../../.., snippet includes -> ../, terminator images) and the cross-references from tools.rst and sas/index.rst were rewritten; :ref: labels are path-independent. A full local sphinx html build reproduces the exact pre-existing warning set (mermaid/mmdc-absent, upstream 404, title underlines) with no broken references. --- docs/source/{ => actions}/action_clients.rst | 20 +++--- docs/source/{ => actions}/action_servers.rst | 18 ++--- docs/source/{ => actions}/actions.rst | 2 +- docs/source/conf.py | 33 ++++++++- docs/source/index.rst | 68 +++++++++---------- .../create_interface_package.rst | 30 ++++---- docs/source/{ => interfaces}/interfaces.rst | 0 .../{ => messages}/inspecting_topics.rst | 0 .../publishers_and_subscribers.rst | 28 ++++---- .../source/{ => packages}/create_packages.rst | 0 .../create_python_node_with_template.rst | 0 .../{ => packages}/create_python_package.rst | 0 docs/source/{ => packages}/running_node.rst | 0 .../{ => packages}/source_after_build.rst | 0 .../inspecting_parameters.rst | 0 .../launch_configurable_nodes.rst | 0 .../parameters_and_launch.rst | 28 ++++---- .../create_python_library.rst | 14 ++-- .../using_python_library.rst | 10 +-- .../create_python_node_from_scratch.rst | 14 ++-- .../python_node_explained.rst | 16 ++--- docs/source/requirements.txt | 1 + docs/source/sas/index.rst | 2 +- .../{ => services}/inspecting_services.rst | 10 +-- .../service_servers_and_clients.rst | 42 ++++++------ docs/source/{ => setup}/installation.rst | 0 docs/source/{ => setup}/terminator.rst | 4 +- docs/source/{ => setup}/workspace_setup.rst | 0 docs/source/tools.rst | 6 +- 29 files changed, 189 insertions(+), 157 deletions(-) rename docs/source/{ => actions}/action_clients.rst (92%) rename docs/source/{ => actions}/action_servers.rst (92%) rename docs/source/{ => actions}/actions.rst (99%) rename docs/source/{ => interfaces}/create_interface_package.rst (87%) rename docs/source/{ => interfaces}/interfaces.rst (100%) rename docs/source/{ => messages}/inspecting_topics.rst (100%) rename docs/source/{ => messages}/publishers_and_subscribers.rst (84%) rename docs/source/{ => packages}/create_packages.rst (100%) rename docs/source/{ => packages}/create_python_node_with_template.rst (100%) rename docs/source/{ => packages}/create_python_package.rst (100%) rename docs/source/{ => packages}/running_node.rst (100%) rename docs/source/{ => packages}/source_after_build.rst (100%) rename docs/source/{ => parameters_and_launch}/inspecting_parameters.rst (100%) rename docs/source/{ => parameters_and_launch}/launch_configurable_nodes.rst (100%) rename docs/source/{ => parameters_and_launch}/parameters_and_launch.rst (81%) rename docs/source/{ => python_library}/create_python_library.rst (88%) rename docs/source/{ => python_library}/using_python_library.rst (88%) rename docs/source/{ => python_node}/create_python_node_from_scratch.rst (86%) rename docs/source/{ => python_node}/python_node_explained.rst (84%) rename docs/source/{ => services}/inspecting_services.rst (93%) rename docs/source/{ => services}/service_servers_and_clients.rst (82%) rename docs/source/{ => setup}/installation.rst (100%) rename docs/source/{ => setup}/terminator.rst (91%) rename docs/source/{ => setup}/workspace_setup.rst (100%) diff --git a/docs/source/action_clients.rst b/docs/source/actions/action_clients.rst similarity index 92% rename from docs/source/action_clients.rst rename to docs/source/actions/action_clients.rst index a2813e6..1fa1692 100644 --- a/docs/source/action_clients.rst +++ b/docs/source/actions/action_clients.rst @@ -1,7 +1,7 @@ Action Clients ============== -.. include:: the_topic_is_under_heavy_construction.rst +.. include:: ../the_topic_is_under_heavy_construction.rst .. versionadded:: Jazzy @@ -70,9 +70,9 @@ Action Client #. Create the Node with an :code:`ActionClient`. #. Update the :file:`setup.py` so that :program:`ros2 run` finds the node (if needed). -:download:`move_straight_in_2d_action_client_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py>` +:download:`move_straight_in_2d_action_client_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py :language: python :lines: 24- :linenos: @@ -87,7 +87,7 @@ In the action client, we will have to manage two instances of :code:`Future`. On It is important to keep them as attributes of the instance to guarantee they will not get out of scope before the result is obtained. This is done as follows. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py :language: python :lines: 37-45 :emphasize-lines: 4,7,8 @@ -102,7 +102,7 @@ Whenever a feedback is sent, the method we assign as callback will be called. After we send the goal request and assign a callback for the feedback, we assign another callback. This second callback is for the result of the goal request operation. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py :language: python :lines: 47-57 :emphasize-lines: 1,5,10,11 @@ -113,7 +113,7 @@ to ask for a result. We ask for a result asynchronously. We then assign a third callback for when a response is sent. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py :language: python :lines: 59-68 :emphasize-lines: 1,4,9,10 @@ -121,13 +121,13 @@ We ask for a result asynchronously. We then assign a third callback for when a r The result callback will receive a future and process the result of the action somehow. In this toy example, we simply print the results to the screen. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py :language: python :lines: 70-72 Lastly, we see that the callback for the feedback is, again, very similar to that for a subscriber. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py :language: python :lines: 74-76 @@ -137,7 +137,7 @@ the action is triggered only once. When doing so, please remember to call the action after the node is instantiated and before :code:`rclpy.spin()`. Otherwise, the object will not yet exist, or you will be locked in the spinner before sending the goal. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_client_node.py :language: python :lines: 87-95 @@ -146,7 +146,7 @@ Build and source Before we proceed, let us build and source once. -.. include:: the_canonical_build_command.rst +.. include:: ../the_canonical_build_command.rst Testing the Action Client ------------------------- diff --git a/docs/source/action_servers.rst b/docs/source/actions/action_servers.rst similarity index 92% rename from docs/source/action_servers.rst rename to docs/source/actions/action_servers.rst index 8a86f92..465483c 100644 --- a/docs/source/action_servers.rst +++ b/docs/source/actions/action_servers.rst @@ -1,7 +1,7 @@ Action Servers ============== -.. include:: the_topic_is_under_heavy_construction.rst +.. include:: ../the_topic_is_under_heavy_construction.rst .. versionadded:: Jazzy @@ -72,9 +72,9 @@ In this section, we will do the following. Let us create the action server as follows. -:download:`move_straight_in_2d_action_server_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py>` +:download:`move_straight_in_2d_action_server_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py :language: python :lines: 24- :linenos: @@ -84,7 +84,7 @@ As always, our class must inherit from :code:`rclpy.node.Node`, so that it can b An action server is an instance of :code:`rclpy.action.ActionServer`. As input to the initializer of :code:`ActionServer`, we need an action, a string that names this action server, and a suitable callback. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py :language: python :lines: 37-50 :emphasize-lines: 1, 10 @@ -107,7 +107,7 @@ not set a goal as succeeded, it will automatically be aborted at the end of the Lastly, the method must return an instance of :code:`MyAction.Result`. In our case, we have the field :code:`final_position` in the action file description, therefore we populate it as needed. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py :language: python :lines: 85-116 :emphasize-lines: 1, 7, 12, 18, 24, 30, 32 @@ -116,7 +116,7 @@ The other methods are to support the important aspects of the action server. The the Euclidean distance between :code:`current_position` and :code:`desired_position`. Remember :ref:`The distance equation `. This is represented by the following piece of code. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py :language: python :lines: 54-65 :emphasize-lines: 1, 12 @@ -124,7 +124,7 @@ This is represented by the following piece of code. The action server will update the :code:`current_position` based on a simple constant speed motion of the point. Remember :ref:`The controller equation `. This is represented by the following piece of code. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/python_package_that_uses_the_actions/move_straight_in_2d_action_server_node.py :language: python :lines: 67-82 @@ -137,7 +137,7 @@ Adjusting the :file:`setup.py` This file will include the directives for the server and client. The one for the server is highlighted below. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/setup.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_actions/setup.py :language: python :emphasize-lines: 23 @@ -146,7 +146,7 @@ Build and source Before we proceed, let us build and source once. -.. include:: the_canonical_build_command.rst +.. include:: ../the_canonical_build_command.rst Testing the Action Server ------------------------- diff --git a/docs/source/actions.rst b/docs/source/actions/actions.rst similarity index 99% rename from docs/source/actions.rst rename to docs/source/actions/actions.rst index 7175d35..ab2e965 100644 --- a/docs/source/actions.rst +++ b/docs/source/actions/actions.rst @@ -1,7 +1,7 @@ Call for Actions: Action Servers and Clients ============================================ -.. include:: the_topic_is_under_heavy_construction.rst +.. include:: ../the_topic_is_under_heavy_construction.rst .. versionadded:: Jazzy diff --git a/docs/source/conf.py b/docs/source/conf.py index cda0142..13974a0 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -33,11 +33,42 @@ 'sphinx_design', # https://sphinx-design.readthedocs.io/en/latest/get_started.html 'sphinxext.remoteliteralinclude', # https://github.com/wpilibsuite/sphinxext-remoteliteralinclude 'sphinxcontrib.mermaid', #https://sphinxcontrib-mermaid-demo.readthedocs.io/en/latest/ - 'sphinxcontrib.bibtex' #https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html + 'sphinxcontrib.bibtex', #https://sphinxcontrib-bibtex.readthedocs.io/en/latest/quickstart.html + 'sphinx_reredirects' #https://gitlab.com/jborean93/sphinx-reredirects ] bibtex_bibfiles = ['refs.bib'] +# Old page locations from the topic-directory reorganisation (the pages were +# git mv'ed into per-topic folders, e.g. installation -> setup/installation). +# sphinx_reredirects emits meta-refresh pages for these during the html build. +redirects = { + 'installation': 'setup/installation', + 'terminator': 'setup/terminator', + 'workspace_setup': 'setup/workspace_setup', + 'create_packages': 'packages/create_packages', + 'create_python_package': 'packages/create_python_package', + 'create_python_node_with_template': 'packages/create_python_node_with_template', + 'source_after_build': 'packages/source_after_build', + 'running_node': 'packages/running_node', + 'create_python_node_from_scratch': 'python_node/create_python_node_from_scratch', + 'python_node_explained': 'python_node/python_node_explained', + 'create_python_library': 'python_library/create_python_library', + 'using_python_library': 'python_library/using_python_library', + 'interfaces': 'interfaces/interfaces', + 'create_interface_package': 'interfaces/create_interface_package', + 'publishers_and_subscribers': 'messages/publishers_and_subscribers', + 'inspecting_topics': 'messages/inspecting_topics', + 'parameters_and_launch': 'parameters_and_launch/parameters_and_launch', + 'launch_configurable_nodes': 'parameters_and_launch/launch_configurable_nodes', + 'inspecting_parameters': 'parameters_and_launch/inspecting_parameters', + 'service_servers_and_clients': 'services/service_servers_and_clients', + 'inspecting_services': 'services/inspecting_services', + 'actions': 'actions/actions', + 'action_servers': 'actions/action_servers', + 'action_clients': 'actions/action_clients', +} + intersphinx_mapping = { 'python': ('https://docs.python.org/3.12/', None), 'sphinx': ('https://www.sphinx-doc.org/en/master/', None), diff --git a/docs/source/index.rst b/docs/source/index.rst index 1f7070f..c4d7b9b 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -38,7 +38,7 @@ These tutorials have been the backbone of `EEEN62021 Software for Robotics ` if they are somewhat already comfortable in Python and Ubuntu. Otherwise, all steps can be considered as dependent on the prior ones, starting from :doc:`ROS2 Setup `. +This is a tutorial that supposes that the user will follow it linearly. Some readers can skip the :doc:`Preamble ` if they are somewhat already comfortable in Python and Ubuntu. Otherwise, all steps can be considered as dependent on the prior ones, starting from :doc:`ROS2 Setup `. It is expected that the user will be working directly on an Ubuntu machine. :program:`Docker` images are available but no compatibility with host systems other than Ubuntu has been attempted. @@ -57,31 +57,31 @@ If you enjoyed this tutorial, please #. :doc:`Preamble: Python Best Practices ` A quick memory refresher for the Python stuff useful in ROS2. -#. :doc:`ROS2 Setup ` (⭐start here⭐) +#. :doc:`ROS2 Setup ` (⭐start here⭐) Installing ROS2 and setting up its environment for use. -#. :doc:`ROS2 Python Package/Build ` +#. :doc:`ROS2 Python Package/Build ` Creating our first ROS2 package with :program:`ament_python` and building it with :program:`colcon`. -#. :doc:`ROS2 Python Node ` +#. :doc:`ROS2 Python Node ` Creating ``rclpy`` Nodes and figuring out what all that means. -#. :doc:`ROS2 Python Library ` +#. :doc:`ROS2 Python Library ` Create Python libraries and importing/using them in another :program:`ament_python` package. -#. :doc:`ROS2 Interfaces ` +#. :doc:`ROS2 Interfaces ` ROS2 interfaces, i.e., messages ``.msg``, services ``.srv``, and actions ``.action``. Creating custom interface packages with :program:`ament_cmake`. -#. :doc:`ROS2 Messages in Python ` +#. :doc:`ROS2 Messages in Python ` Writing and using ROS2 messages, publishers, and subscribers. -#. :doc:`ROS2 Parameter/Launch ` +#. :doc:`ROS2 Parameter/Launch ` Making configurable ROS2 Nodes using parameters and launch files. -#. :doc:`ROS2 Services in Python ` +#. :doc:`ROS2 Services in Python ` Writing ROS2 services, service servers, and service clients. -#. :doc:`ROS2 Actions in Python ` +#. :doc:`ROS2 Actions in Python ` Writing ROS2 actions, action servers, and action clients. #. :doc:`Frame Transformations ` @@ -112,78 +112,78 @@ If you enjoyed this tutorial, please :maxdepth: 2 :hidden: - installation - terminator - workspace_setup + setup/installation + setup/terminator + setup/workspace_setup .. toctree:: :caption: ROS2 Python Package/Build :maxdepth: 2 :hidden: - create_packages - create_python_package - create_python_node_with_template - source_after_build - running_node + packages/create_packages + packages/create_python_package + packages/create_python_node_with_template + packages/source_after_build + packages/running_node .. toctree:: :caption: ROS2 Python Node :maxdepth: 2 :hidden: - create_python_node_from_scratch - python_node_explained + python_node/create_python_node_from_scratch + python_node/python_node_explained .. toctree:: :caption: ROS2 Python Library :maxdepth: 2 :hidden: - create_python_library - using_python_library + python_library/create_python_library + python_library/using_python_library .. toctree:: :caption: ROS2 Interfaces: Messages, Services, and Actions :maxdepth: 2 :hidden: - interfaces - create_interface_package + interfaces/interfaces + interfaces/create_interface_package .. toctree:: :caption: ROS2 Messages in Python :maxdepth: 2 :hidden: - publishers_and_subscribers - inspecting_topics + messages/publishers_and_subscribers + messages/inspecting_topics .. toctree:: :caption: ROS2 Parameter/Launch :maxdepth: 2 :hidden: - parameters_and_launch - launch_configurable_nodes - inspecting_parameters + parameters_and_launch/parameters_and_launch + parameters_and_launch/launch_configurable_nodes + parameters_and_launch/inspecting_parameters .. toctree:: :caption: ROS2 Services in Python :maxdepth: 2 :hidden: - service_servers_and_clients - inspecting_services + services/service_servers_and_clients + services/inspecting_services .. toctree:: :caption: ROS2 Actions in Python :maxdepth: 2 :hidden: - actions - action_servers - action_clients + actions/actions + actions/action_servers + actions/action_clients .. toctree:: :caption: Frame transformations and tf2 diff --git a/docs/source/create_interface_package.rst b/docs/source/interfaces/create_interface_package.rst similarity index 87% rename from docs/source/create_interface_package.rst rename to docs/source/interfaces/create_interface_package.rst index 09285e2..61df863 100644 --- a/docs/source/create_interface_package.rst +++ b/docs/source/interfaces/create_interface_package.rst @@ -90,9 +90,9 @@ The :file:`package.xml` dependencies Whenever the package has any type of interface, the :file:`package.xml` **must** include three specific dependencies. Namely, the ones highlighted below. Edit the :file:`package_with_interfaces/package.xml` like so -:download:`package.xml <../../ros2_tutorial_workspace/src/package_with_interfaces/package.xml>` +:download:`package.xml <../../../ros2_tutorial_workspace/src/package_with_interfaces/package.xml>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/package_with_interfaces/package.xml +.. literalinclude:: ../../../ros2_tutorial_workspace/src/package_with_interfaces/package.xml :language: xml :linenos: :emphasize-lines: 14-16 @@ -125,9 +125,9 @@ Let us create a message file to transfer inspirational quotes between Nodes. For There are many ways to represent this, but for the sake of the example let us give each message an :code:`id` and two rather obvious fields. Create a file called :file:`AmazingQuote.msg` in the folder :file:`msg` that we just created with the following contents. -:download:`AmazingQuote.msg <../../ros2_tutorial_workspace/src/package_with_interfaces/msg/AmazingQuote.msg>` +:download:`AmazingQuote.msg <../../../ros2_tutorial_workspace/src/package_with_interfaces/msg/AmazingQuote.msg>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/package_with_interfaces/msg/AmazingQuote.msg +.. literalinclude:: ../../../ros2_tutorial_workspace/src/package_with_interfaces/msg/AmazingQuote.msg :language: yaml :linenos: @@ -141,9 +141,9 @@ Re-using a message from the same package With the :file:`AmazingQuote.msg`, we have seen how to use built-in types. Let's use another message, :file:`AmazingQuoteStamped.msg`, to learn two more possibilities, namely using messages from the same package and messages defined elsewhere. -:download:`AmazingQuoteStamped.msg <../../ros2_tutorial_workspace/src/package_with_interfaces/msg/AmazingQuoteStamped.msg>` +:download:`AmazingQuoteStamped.msg <../../../ros2_tutorial_workspace/src/package_with_interfaces/msg/AmazingQuoteStamped.msg>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/package_with_interfaces/msg/AmazingQuoteStamped.msg +.. literalinclude:: ../../../ros2_tutorial_workspace/src/package_with_interfaces/msg/AmazingQuoteStamped.msg :language: yaml :linenos: @@ -169,9 +169,9 @@ The service file Add the file :file:`AddPoints.srv` in the :file:`srv` folder with the following contents -:download:`AddPoints.srv <../../ros2_tutorial_workspace/src/package_with_interfaces/srv/AddPoints.srv>` +:download:`AddPoints.srv <../../../ros2_tutorial_workspace/src/package_with_interfaces/srv/AddPoints.srv>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/package_with_interfaces/srv/AddPoints.srv +.. literalinclude:: ../../../ros2_tutorial_workspace/src/package_with_interfaces/srv/AddPoints.srv :language: yaml :linenos: @@ -192,9 +192,9 @@ The action file Add the file :file:`MoveStraightIn2D.action` in the :file:`action` folder with the following contents -:download:`MoveStraightIn2D.action <../../ros2_tutorial_workspace/src/package_with_interfaces/action/MoveStraightIn2D.action>` +:download:`MoveStraightIn2D.action <../../../ros2_tutorial_workspace/src/package_with_interfaces/action/MoveStraightIn2D.action>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/package_with_interfaces/action/MoveStraightIn2D.action +.. literalinclude:: ../../../ros2_tutorial_workspace/src/package_with_interfaces/action/MoveStraightIn2D.action :language: yaml :linenos: @@ -209,9 +209,9 @@ The :file:`CMakeLists.txt` directives If a package is dedicated to interfaces, there is no need to worry too much about the :program:`CMake` details. We can follow the boilerplate as shown below. Edit the :file:`package_with_interfaces/CMakeLists.txt` like so -:download:`CMakeLists.txt <../../ros2_tutorial_workspace/src/package_with_interfaces/CMakeLists.txt>` +:download:`CMakeLists.txt <../../../ros2_tutorial_workspace/src/package_with_interfaces/CMakeLists.txt>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/package_with_interfaces/CMakeLists.txt +.. literalinclude:: ../../../ros2_tutorial_workspace/src/package_with_interfaces/CMakeLists.txt :language: cmake :linenos: :emphasize-lines: 14-40 @@ -233,7 +233,7 @@ If additional interfaces are required #. Add each new interface file to :code:`set(interface_files ...)` - .. literalinclude:: ../../ros2_tutorial_workspace/src/package_with_interfaces/CMakeLists.txt + .. literalinclude:: ../../../ros2_tutorial_workspace/src/package_with_interfaces/CMakeLists.txt :language: cmake :lines: 17-28 :emphasize-lines: 5,8,11 @@ -247,7 +247,7 @@ Build and source Before we proceed, let us build and source once. -.. include:: the_canonical_build_command.rst +.. include:: ../the_canonical_build_command.rst Getting info on custom interfaces --------------------------------- @@ -277,7 +277,7 @@ and we can further get more specific info on :file:`AmazingQuote` (or :file:`Ama which returns -.. literalinclude:: ../../ros2_tutorial_workspace/src/package_with_interfaces/msg/AmazingQuote.msg +.. literalinclude:: ../../../ros2_tutorial_workspace/src/package_with_interfaces/msg/AmazingQuote.msg :language: yaml alternatively, we can do the same for :file:`AddPoints` diff --git a/docs/source/interfaces.rst b/docs/source/interfaces/interfaces.rst similarity index 100% rename from docs/source/interfaces.rst rename to docs/source/interfaces/interfaces.rst diff --git a/docs/source/inspecting_topics.rst b/docs/source/messages/inspecting_topics.rst similarity index 100% rename from docs/source/inspecting_topics.rst rename to docs/source/messages/inspecting_topics.rst diff --git a/docs/source/publishers_and_subscribers.rst b/docs/source/messages/publishers_and_subscribers.rst similarity index 84% rename from docs/source/publishers_and_subscribers.rst rename to docs/source/messages/publishers_and_subscribers.rst index 0e9fe20..7f8709f 100644 --- a/docs/source/publishers_and_subscribers.rst +++ b/docs/source/messages/publishers_and_subscribers.rst @@ -136,9 +136,9 @@ Create the Node with a publisher For the publisher, create a file called :file:`amazing_quote_publisher_node.py`, with the following contents -:download:`amazing_quote_publisher_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py>` +:download:`amazing_quote_publisher_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py :language: python :linenos: :lines: 24- @@ -146,14 +146,14 @@ For the publisher, create a file called :file:`amazing_quote_publisher_node.py`, When we built our :file:`package_with_interfaces` in the last section, what ROS2 did for us, among other things, was create a Python library called :file:`package_with_interfaces.msg` containing the Python implementation of the :file:`AmazingQuote.msg`. Because of that, we can use it by importing it like so -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py :language: python :lines: 24-29 :emphasize-lines: 4 The publisher must be created with the :code:`Node.create_publisher(...)` method, which has the three parameters defined in the :ref:`publisher and subscriber parameter table`. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py :language: python :lines: 38-41 @@ -176,13 +176,13 @@ The publisher must be created with the :code:`Node.create_publisher(...)` method Then, each message is handled much like any other class in Python. We instantiate and initialize the message as follows -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py :language: python :lines: 51-54 Lastly, the message needs to be published using :code:`Node.publish(msg)`. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_publisher_node.py :language: python :lines: 56 @@ -206,9 +206,9 @@ Create the Node with a subscriber For the subscriber Node, create a file in :file:`python_package_that_uses_the_messages/python_package_that_uses_the_messages` called :file:`amazing_quote_subscriber_node.py`, with the following contents -:download:`amazing_quote_subscriber_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_subscriber_node.py>` +:download:`amazing_quote_subscriber_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_subscriber_node.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_subscriber_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_subscriber_node.py :language: python :linenos: :lines: 24- @@ -216,21 +216,21 @@ For the subscriber Node, create a file in :file:`python_package_that_uses_the_me Similarly to the publisher, in the subscriber, we start by importing the message in question -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_subscriber_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_subscriber_node.py :language: python :lines: 24-28 :emphasize-lines: 4 Then, in our subclass of :code:`Node`, we call :code:`Node.create_subscription(...)` as follows -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_subscriber_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_subscriber_node.py :language: python :lines: 36-40 :emphasize-lines: 4 where the only difference with respect to the publisher is the third argument, namely :code:`callback`, in which a method that receives a :code:`msg_type` and returns nothing is expected. For example, the :code:`amazing_quote_subscriber_callback`. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_subscriber_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/python_package_that_uses_the_messages/amazing_quote_subscriber_node.py :language: python :lines: 42-55 :emphasize-lines: 8,12,14 @@ -246,9 +246,9 @@ Update the :file:`setup.py` As we already learned in :ref:`Making rosrun work`, we must adjust the :file:`setup.py` to refer to the Nodes we just created. -:download:`setup.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/setup.py>` +:download:`setup.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/setup.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/setup.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_messages/setup.py :language: python :linenos: :emphasize-lines: 21-25 @@ -258,7 +258,7 @@ Build and source Before we proceed, let us build and source once. -.. include:: the_canonical_build_command.rst +.. include:: ../the_canonical_build_command.rst Testing Publisher and Subscriber -------------------------------- diff --git a/docs/source/create_packages.rst b/docs/source/packages/create_packages.rst similarity index 100% rename from docs/source/create_packages.rst rename to docs/source/packages/create_packages.rst diff --git a/docs/source/create_python_node_with_template.rst b/docs/source/packages/create_python_node_with_template.rst similarity index 100% rename from docs/source/create_python_node_with_template.rst rename to docs/source/packages/create_python_node_with_template.rst diff --git a/docs/source/create_python_package.rst b/docs/source/packages/create_python_package.rst similarity index 100% rename from docs/source/create_python_package.rst rename to docs/source/packages/create_python_package.rst diff --git a/docs/source/running_node.rst b/docs/source/packages/running_node.rst similarity index 100% rename from docs/source/running_node.rst rename to docs/source/packages/running_node.rst diff --git a/docs/source/source_after_build.rst b/docs/source/packages/source_after_build.rst similarity index 100% rename from docs/source/source_after_build.rst rename to docs/source/packages/source_after_build.rst diff --git a/docs/source/inspecting_parameters.rst b/docs/source/parameters_and_launch/inspecting_parameters.rst similarity index 100% rename from docs/source/inspecting_parameters.rst rename to docs/source/parameters_and_launch/inspecting_parameters.rst diff --git a/docs/source/launch_configurable_nodes.rst b/docs/source/parameters_and_launch/launch_configurable_nodes.rst similarity index 100% rename from docs/source/launch_configurable_nodes.rst rename to docs/source/parameters_and_launch/launch_configurable_nodes.rst diff --git a/docs/source/parameters_and_launch.rst b/docs/source/parameters_and_launch/parameters_and_launch.rst similarity index 81% rename from docs/source/parameters_and_launch.rst rename to docs/source/parameters_and_launch/parameters_and_launch.rst index 7fd22d5..4d19afd 100644 --- a/docs/source/parameters_and_launch.rst +++ b/docs/source/parameters_and_launch/parameters_and_launch.rst @@ -62,9 +62,9 @@ For the sake of the example, let us suppose that we want to make an :code:`Amazi Let's start by creating an :file:`amazing_quote_configurable_publisher_node.py` in :file:`python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files` with the following contents -:download:`amazing_quote_configurable_publisher_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files/amazing_quote_configurable_publisher_node.py>` +:download:`amazing_quote_configurable_publisher_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files/amazing_quote_configurable_publisher_node.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files/amazing_quote_configurable_publisher_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files/amazing_quote_configurable_publisher_node.py :language: python :lines: 24- :linenos: @@ -89,7 +89,7 @@ One-off parameters For one-off parameters, we just get them once after declaring them. Because we're using those attributes directly in the :code:`__init__` method, they are not made attributes of the class, but they could be. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files/amazing_quote_configurable_publisher_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files/amazing_quote_configurable_publisher_node.py :language: python :lines: 42-53 :emphasize-lines: 2-5,9,12 @@ -106,13 +106,13 @@ Continuously-obtained parameters For parameters that we obtain continuously through the lifetime of the Node, we can, for example, declare them in the :code:`__init__` method, like so -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files/amazing_quote_configurable_publisher_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files/amazing_quote_configurable_publisher_node.py :language: python :lines: 38-40 then obtain them in another method, like so -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files/amazing_quote_configurable_publisher_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/python_package_that_uses_parameters_and_launch_files/amazing_quote_configurable_publisher_node.py :language: python :lines: 57-70 :emphasize-lines: 4,5,9,10 @@ -195,34 +195,34 @@ Create the :file:`launch` file Suppose that we are tired of all the meme quotes and want to make our Node publish a truly inspirational quote. We start by making the launch file named :file:`peanut_butter_falcon_quote_publisher_launch.py` within the :file:`launch` folder we just created, with the following contents -:download:`peanut_butter_falcon_quote_publisher_launch.py <../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py>` +:download:`peanut_butter_falcon_quote_publisher_launch.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py :language: python :linenos: We're relying on the :code:`LaunchDescription`, which expects a list of :code:`launch_ros.actions`. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py :language: python :lines: 1,2 When using a :code:`launch_ros.actions.Node`, we need to define which :file:`package` it belongs to and the :file:`executable` which must match the name we set for the executable in the :file:`setup.py` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py :language: python :lines: 10,11 Besides the parameters, we can configure the name of the Node, such that each is unique -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py :language: python :lines: 12 Finally, our parameters are defined using a dictionary within a list, namely -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/launch/peanut_butter_falcon_quote_publisher_launch.py :language: python :lines: 14-18 @@ -252,9 +252,9 @@ The :file:`setup.py` Modify the :file:`setup.py` to look like this -:download:`setup.py <../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/setup.py>` +:download:`setup.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/setup.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/setup.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_parameters_and_launch_files/setup.py :language: python :linenos: :emphasize-lines: 15,25-27 @@ -269,4 +269,4 @@ Build and source Before we proceed, let us build and source once. -.. include:: the_canonical_build_command.rst +.. include:: ../the_canonical_build_command.rst diff --git a/docs/source/create_python_library.rst b/docs/source/python_library/create_python_library.rst similarity index 88% rename from docs/source/create_python_library.rst rename to docs/source/python_library/create_python_library.rst index 6b20785..6bb810c 100644 --- a/docs/source/create_python_library.rst +++ b/docs/source/python_library/create_python_library.rst @@ -141,9 +141,9 @@ Create the sample function Create a new file with the following contents and name. -:download:`_sample_function.py <../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/_sample_function.py>` +:download:`_sample_function.py <../../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/_sample_function.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/_sample_function.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/_sample_function.py :language: python :linenos: :lines: 26- @@ -155,9 +155,9 @@ Create the sample class Create a new file with the following contents and name. -:download:`_sample_class.py <../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/_sample_class.py>` +:download:`_sample_class.py <../../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/_sample_class.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/_sample_class.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/_sample_class.py :language: python :linenos: :lines: 26- @@ -167,9 +167,9 @@ The class is quite simple with a `private data member ` +:download:`__init__.py <../../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/__init__.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/__init__.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_library/python_package_with_a_library/sample_python_library/__init__.py :language: python :linenos: :lines: 24- @@ -184,6 +184,6 @@ Build and source No surprise here, right? -.. include:: the_canonical_build_command.rst +.. include:: ../the_canonical_build_command.rst If it builds without any unexpected issues, we're good to go! diff --git a/docs/source/using_python_library.rst b/docs/source/python_library/using_python_library.rst similarity index 88% rename from docs/source/using_python_library.rst rename to docs/source/python_library/using_python_library.rst index 3120e3d..d350204 100644 --- a/docs/source/using_python_library.rst +++ b/docs/source/python_library/using_python_library.rst @@ -85,23 +85,23 @@ The sample Node Given that it was created from a template, the file :file:`library_user_node.py` is currently *mostly* empty. Let us replace its contents with -:download:`library_user_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_library/python_package_that_uses_the_library/library_user_node.py>` +:download:`library_user_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_library/python_package_that_uses_the_library/library_user_node.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_library/python_package_that_uses_the_library/library_user_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_library/python_package_that_uses_the_library/library_user_node.py :language: python :linenos: :lines: 24- Indeed, the most difficult part is to make and configure the library itself. After that, to use it in another package, it is straightforward. We :code:`import` the library. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_library/python_package_that_uses_the_library/library_user_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_library/python_package_that_uses_the_library/library_user_node.py :language: python :lines: 24-31 :emphasize-lines: 7 And then use the symbols we imported as we would with any other Python library. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_library/python_package_that_uses_the_library/library_user_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_library/python_package_that_uses_the_library/library_user_node.py :language: python :lines: 42-57 :emphasize-lines: 10, 14 @@ -111,7 +111,7 @@ Build and source As always, this is needed so that our new package and node can be recognized by :program:`ros2 run`. -.. include:: the_canonical_build_command.rst +.. include:: ../the_canonical_build_command.rst Run --- diff --git a/docs/source/create_python_node_from_scratch.rst b/docs/source/python_node/create_python_node_from_scratch.rst similarity index 86% rename from docs/source/create_python_node_from_scratch.rst rename to docs/source/python_node/create_python_node_from_scratch.rst index 19c08b5..ab815a7 100644 --- a/docs/source/create_python_node_from_scratch.rst +++ b/docs/source/python_node/create_python_node_from_scratch.rst @@ -53,9 +53,9 @@ By no coincidence, the :file:`package.xml` has the :code:`.xml` extension, meani Let us add the dependency between the :code:`` and :code:`` tags. This is not a strict requirement but is where it commonly is for standard packages. -:download:`package.xml <../../ros2_tutorial_workspace/src/python_package_with_a_node/package.xml>` +:download:`package.xml <../../../ros2_tutorial_workspace/src/python_package_with_a_node/package.xml>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/package.xml +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_node/package.xml :language: xml :linenos: :emphasize-lines: 10 @@ -65,9 +65,9 @@ Creating the Node In the directory :file:`src/python_package_with_a_node/python_package_with_a_node`, create a new file called :file:`print_forever_node.py`. Copy and paste the following contents into the file. -:download:`print_forever_node.py <../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py>` +:download:`print_forever_node.py <../../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py :language: python :linenos: :lines: 24- @@ -85,9 +85,9 @@ To do so, we modify the :code:`console_scripts` key in the :code:`entry_points` :code:`console_scripts` expects a :code:`list` of :code:`str` in a specific format. Hence, follow the format properly and don't forget the commas to separate elements in the :code:`list`. -:download:`setup.py <../../ros2_tutorial_workspace/src/python_package_with_a_node/setup.py>` +:download:`setup.py <../../../ros2_tutorial_workspace/src/python_package_with_a_node/setup.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/setup.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_node/setup.py :language: python :linenos: :emphasize-lines: 24 @@ -106,7 +106,7 @@ Build and source We can build and source the workspace with the following command. -.. include:: the_canonical_build_command.rst +.. include:: ../the_canonical_build_command.rst Test ---- diff --git a/docs/source/python_node_explained.rst b/docs/source/python_node/python_node_explained.rst similarity index 84% rename from docs/source/python_node_explained.rst rename to docs/source/python_node/python_node_explained.rst index d08b703..810083f 100644 --- a/docs/source/python_node_explained.rst +++ b/docs/source/python_node/python_node_explained.rst @@ -10,7 +10,7 @@ In a strict sense, the :file:`print_forever_node.py` is not a minimal Node, but The imports ----------- -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py :language: python :lines: 24-25 @@ -21,7 +21,7 @@ Making a subclass of :code:`Node` The current version of ROS2 behaves better when your custom Node is a subclass of :code:`rclpy.node.Node`. That is achieved with -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py :language: python :lines: 30-35 :emphasize-lines: 1,5 @@ -43,14 +43,14 @@ In its most basic usage, periodic tasks in ROS2 must be handled by a `Timer `_ the program and, well, **spin** through Timer callbacks forever. There are alternative ways to :code:`spin()`, but we will not discuss them right now. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py :language: python :lines: 45-60 :emphasize-lines: 8,12 @@ -84,7 +84,7 @@ However, when running Nodes either in the terminal or in :program:`PyCharm`, cat That is particularly important when real robots need to be gracefully shut down (otherwise they might inadvertently start the evil robot uprising), but it also looks unprofessional when all your Nodes return with an ugly stack trace. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py :language: python :lines: 45-60 :emphasize-lines: 7,13 @@ -112,14 +112,14 @@ Add as much description as possible to classes and methods, using the `Docstring Example of a class: -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py :language: python :lines: 30-31 :emphasize-lines: 2 Example of a method: -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/print_forever_node.py :language: python :lines: 39-40 :emphasize-lines: 2 diff --git a/docs/source/requirements.txt b/docs/source/requirements.txt index 9c0036b..32d97a2 100644 --- a/docs/source/requirements.txt +++ b/docs/source/requirements.txt @@ -5,3 +5,4 @@ sphinxext-remoteliteralinclude sphinx-book-theme sphinxcontrib-mermaid sphinxcontrib-bibtex +sphinx-reredirects diff --git a/docs/source/sas/index.rst b/docs/source/sas/index.rst index 0593760..ee17da0 100644 --- a/docs/source/sas/index.rst +++ b/docs/source/sas/index.rst @@ -15,7 +15,7 @@ Workshops Quick overview -------------- -#. :doc:`Installation ` +#. :doc:`Installation <../setup/installation>` Setting up your system to use `SAS`. #. :doc:`Creating a new SASRobotDriver ` diff --git a/docs/source/inspecting_services.rst b/docs/source/services/inspecting_services.rst similarity index 93% rename from docs/source/inspecting_services.rst rename to docs/source/services/inspecting_services.rst index 1d8c7a4..d847abf 100644 --- a/docs/source/inspecting_services.rst +++ b/docs/source/services/inspecting_services.rst @@ -161,9 +161,9 @@ Note that we are using inheritance from the previously written :code:`AddPointsS The quality-of-service profile is within the same scope as the quality-of-service for messages and has a similar meaning. The :code:`introspection_state` defines how much of the service can be introspected. Less information can be made accessible if that is necessary. - :download:`add_points_service_client_introspection_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_introspection_node.py>` + :download:`add_points_service_client_introspection_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_introspection_node.py>` - .. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_introspection_node.py + .. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_introspection_node.py :language: python :linenos: :lines: 24- @@ -173,9 +173,9 @@ Note that we are using inheritance from the previously written :code:`AddPointsS The service server has the same syntax and requirements to activate introspection as the service client. - :download:`add_points_service_server_introspection_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_introspection_node.py>` + :download:`add_points_service_server_introspection_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_introspection_node.py>` - .. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_introspection_node.py + .. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_introspection_node.py :language: python :linenos: :lines: 24- @@ -186,7 +186,7 @@ Build and source Before we proceed, let us build and source once. -.. include:: the_canonical_build_command.rst +.. include:: ../the_canonical_build_command.rst Finally the :program:`ros2 service echo` ---------------------------------------- diff --git a/docs/source/service_servers_and_clients.rst b/docs/source/services/service_servers_and_clients.rst similarity index 82% rename from docs/source/service_servers_and_clients.rst rename to docs/source/services/service_servers_and_clients.rst index 8daebdd..e1da5b4 100644 --- a/docs/source/service_servers_and_clients.rst +++ b/docs/source/services/service_servers_and_clients.rst @@ -136,28 +136,28 @@ Create the Node with a Service Server Let's start by creating a :file:`add_points_service_server_node.py`. -:download:`add_points_service_server_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py>` +:download:`add_points_service_server_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py :language: python :lines: 24- The code begins with an import to the service we created. No surprise here. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py :language: python :lines: 24-31 :emphasize-lines: 4 The Service Server must be initialised with the :code:`create_service()`, as follows, with parameters that should by now be quite obvious to us. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py :language: python :lines: 37-40 The Service Server receives a :code:`AddPoints.Request` and returns a :code:`AddPoints.Response`. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py :language: python :lines: 44-50 :emphasize-lines: 2,4 @@ -169,7 +169,7 @@ The Service Server receives a :code:`AddPoints.Request` and returns a :code:`Add We use the members of :code:`AddPoints.Request` to calculate and populate the :code:`AddPoints.Response`. At the end of the callback, we must return that :code:`AddPoints.Response`. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_server_node.py :language: python :lines: 52-56 @@ -212,9 +212,9 @@ The Node We start by adding a :file:`add_points_service_client_node.py` at :file:`python_package_that_uses_the_services/python_package_that_uses_the_services` with the following contents. -:download:`add_points_service_client_node.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py>` +:download:`add_points_service_client_node.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :linenos: :lines: 24- @@ -224,7 +224,7 @@ Imports To have access to the service, we import it with :code:`from .srv import `. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :lines: 24-33 :emphasize-lines: 8 @@ -234,7 +234,7 @@ Instantiate a Service Client We instantiate a Service Client with :code:`Node.create_client()`. The values of :code:`srv_type` and :code:`srv_name` must match the ones used in the Service Server. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :lines: 42-44 @@ -246,7 +246,7 @@ We instantiate a Service Client with :code:`Node.create_client()`. The values of In many cases, having the result of the service is of particular importance (hence the use of a service and not messages). In that case, we have to wait until :code:`service_client.wait_for_service()`, as shown below. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :lines: 44,45 @@ -255,7 +255,7 @@ Instantiate a :code:`Future` as a class attribute As part of the :code:`async` framework, we instantiate a :code:`Future` (`More info `_). In this example it is important to have it as an attribute of the class so that we do not lose the reference to it after the callback. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :lines: 49 @@ -264,13 +264,13 @@ Instantiate a Timer Whenever periodic work must be done, it is recommended to use a :code:`Timer`, as we already learned in :ref:`Use a Timer for periodic work`. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :lines: 51-54 The need for a callback for the :code:`Timer`, should also be no surprise. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :lines: 56-57 @@ -279,7 +279,7 @@ Service Clients use :code:`.Request()` Given that services work in a request-response model, the Service Client must instantiate a suitable :code:`.Request()` and populate its fields before making the service call, as shown below. To make the example more interesting, it populates the request with random points. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :lines: 59-67 @@ -298,14 +298,14 @@ There are many ways to address the use of a :code:`Future`. One of them, special The benefit of this is that the callback will not block our resources until the response is ready. When the response is ready, and the ROS2 executor gets to processing :code:`Future` callbacks, our callback will be called *automagically*. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :lines: 69-74 :emphasize-lines: 5,6 Given that we are periodically calling the service, before replacing the class :code:`Future` with the next service call, we can check if the service call was done with :code:`Future.done()`. If it is not done, we can use :code:`Future.cancel()` so that our callback can handle this case as well. For instance, if the Service Server has been shutdown, the :code:`Future` would never be done. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :lines: 69-74 :emphasize-lines: 1-4 @@ -317,7 +317,7 @@ The callback for the :code:`Future` must receive a :code:`Future` as an argument The result of the :code:`Future` is obtained using :code:`Future.result()`. The response might be :code:`None` in some cases, so we must check it before trying to use the result, otherwise we will get a nasty exception. -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/python_package_that_uses_the_services/add_points_service_client_node.py :language: python :lines: 76-82 :emphasize-lines: 1,3,4 @@ -327,9 +327,9 @@ Update the :file:`setup.py` As we already learned in :ref:`Making rosrun work`, we must adjust the :file:`setup.py` to refer to the Nodes we just created. -:download:`setup.py <../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/setup.py>` +:download:`setup.py <../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/setup.py>` -.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/setup.py +.. literalinclude:: ../../../ros2_tutorial_workspace/src/python_package_that_uses_the_services/setup.py :language: python :linenos: :emphasize-lines: 23,24,27,28 @@ -339,7 +339,7 @@ Build and source Before we proceed, let us build and source once. -.. include:: the_canonical_build_command.rst +.. include:: ../the_canonical_build_command.rst Testing Service Server and Client --------------------------------- diff --git a/docs/source/installation.rst b/docs/source/setup/installation.rst similarity index 100% rename from docs/source/installation.rst rename to docs/source/setup/installation.rst diff --git a/docs/source/terminator.rst b/docs/source/setup/terminator.rst similarity index 91% rename from docs/source/terminator.rst rename to docs/source/setup/terminator.rst index 28b4a50..3421d6d 100644 --- a/docs/source/terminator.rst +++ b/docs/source/setup/terminator.rst @@ -28,7 +28,7 @@ For example, pressing the following combination: Will result in three terminal windows that look like so. -.. image:: ../images/terminator_example.png +.. image:: ../../images/terminator_example.png :align: center @@ -38,7 +38,7 @@ OK, but what if shortcuts scare me Instead of using shortcuts, a context menu can be opened by right-clicking a terminal window. Then, you can choose to `Split Horizontally` or `Split Vertically` to achieve the same results. -.. image:: ../images/terminator_right_click_menu.png +.. image:: ../../images/terminator_right_click_menu.png :align: center diff --git a/docs/source/workspace_setup.rst b/docs/source/setup/workspace_setup.rst similarity index 100% rename from docs/source/workspace_setup.rst rename to docs/source/setup/workspace_setup.rst diff --git a/docs/source/tools.rst b/docs/source/tools.rst index a5f0fa6..dc9e639 100644 --- a/docs/source/tools.rst +++ b/docs/source/tools.rst @@ -9,7 +9,7 @@ so there is nothing to install. It checks four groups of things: - **Shutdown template**: every :code:`rclpy.spin()` is wrapped according - to the template of :doc:`The Python Node, explained `, + to the template of :doc:`The Python Node, explained `, i.e., :code:`except (KeyboardInterrupt, ExternalShutdownException): pass` before any broad :code:`except Exception`. - **Naming**: the conventions of :doc:`(Murilo's) Python Best Practices @@ -18,8 +18,8 @@ It checks four groups of things: - **Best practices**: no relative imports, no :code:`destroy_node()`/:code:`rclpy.shutdown()` (the template omits them), :code:`get_logger()` instead of :code:`print()` inside Nodes, and :code:`get_parameter()` only for declared parameters — - from :doc:`The Python Node, explained `, - :doc:`Parameters and Launch ` and + from :doc:`The Python Node, explained `, + :doc:`Parameters and Launch ` and :doc:`(Murilo's) Python Best Practices `. - **Package structure**: package folder matches :code:`` in