[create_packages.rst] Updated to jazzy

Author: Murilo Marinho

docs/source/conf.py

@@ -32,6 +32,7 @@
     'sphinx_copybutton', # https://sphinx-copybutton.readthedocs.io/en/latest/
     'sphinx_design', # https://sphinx-design.readthedocs.io/en/latest/get_started.html
     "sphinxext.remoteliteralinclude" # https://github.com/wpilibsuite/sphinxext-remoteliteralinclude
+
 ]
 
 intersphinx_mapping = {
@@ -48,7 +49,8 @@
 # Tried with `furo` on May 23, 2025, but somehow it didn't look right. In particular the download button wasn't as clear.
 html_theme_options = {
    "announcement": "The documentation is being updated to Jazzy in this branch. "
-                   "See <a href='https://ros2-tutorial.readthedocs.io/en/humble/'>Humble Docs</a> for the stable ones",
+                   "See <a href='https://ros2-tutorial.readthedocs.io/en/humble/'>Humble Docs</a> for the stable ones. "
+                   "Create an <a href='https://github.com/mmmarinho/ROS2_Tutorial/issues'>issue</a> for inconsistencies.",
 }
 html_title = project
 

docs/source/create_packages.rst

@@ -10,43 +10,35 @@ ROS2 has a tool to help create package templates. We can get all available optio
 which outputs a list of handy options to populate the package template with useful files. Namely, the four emphasized ones.
 
 .. code-block:: console
-   :emphasize-lines: 27, 29, 35, 37
-
-    usage: ros2 pkg create [-h] [--package-format {2,3}] [--description DESCRIPTION]
-                           [--license LICENSE]
-                           [--destination-directory DESTINATION_DIRECTORY]
-                           [--build-type {cmake,ament_cmake,ament_python}]
-                           [--dependencies DEPENDENCIES [DEPENDENCIES ...]]
-                           [--maintainer-email MAINTAINER_EMAIL]
-                           [--maintainer-name MAINTAINER_NAME] [--node-name NODE_NAME]
-                           [--library-name LIBRARY_NAME]
-                           package_name
-
-    Create a new ROS 2 package
-
-    positional arguments:
-      package_name          The package name
-
-    options:
-      -h, --help            show this help message and exit
-      --package-format {2,3}, --package_format {2,3}
-                            The package.xml format.
-      --description DESCRIPTION
-                            The description given in the package.xml
-      --license LICENSE     The license attached to this package; this can be an arbitrary
-                            string, but a LICENSE file will only be generated if it is one
-                            of the supported licenses (pass '?' to get a list)
-      --destination-directory DESTINATION_DIRECTORY
-                            Directory where to create the package directory
-      --build-type {cmake,ament_cmake,ament_python}
-                            The build type to process the package with
-      --dependencies DEPENDENCIES [DEPENDENCIES ...]
-                            list of dependencies
-      --maintainer-email MAINTAINER_EMAIL
-                            email address of the maintainer of this package
-      --maintainer-name MAINTAINER_NAME
-                            name of the maintainer of this package
-      --node-name NODE_NAME
-                            name of the empty executable
-      --library-name LIBRARY_NAME
-                            name of the empty library
+   :emphasize-lines: 19,21,27, 29
+
+   usage: ros2 pkg create [-h] [--package-format {2,3}] [--description DESCRIPTION] [--license LICENSE] [--destination-directory DESTINATION_DIRECTORY] [--build-type {cmake,ament_cmake,ament_python}]
+                    [--dependencies DEPENDENCIES [DEPENDENCIES ...]] [--maintainer-email MAINTAINER_EMAIL] [--maintainer-name MAINTAINER_NAME] [--node-name NODE_NAME] [--library-name LIBRARY_NAME]
+                    package_name
+
+   Create a new ROS 2 package
+
+   positional arguments:
+     package_name          The package name
+
+   options:
+     -h, --help            show this help message and exit
+     --package-format {2,3}, --package_format {2,3}
+                           The package.xml format.
+     --description DESCRIPTION
+                           The description given in the package.xml
+     --license LICENSE     The license attached to this package; this can be an arbitrary string, but a LICENSE file will only be generated if it is one of the supported licenses (pass '?' to get a list)
+     --destination-directory DESTINATION_DIRECTORY
+                           Directory where to create the package directory
+     --build-type {cmake,ament_cmake,ament_python}
+                           The build type to process the package with
+     --dependencies DEPENDENCIES [DEPENDENCIES ...]
+                           list of dependencies
+     --maintainer-email MAINTAINER_EMAIL
+                           email address of the maintainer of this package
+     --maintainer-name MAINTAINER_NAME
+                           name of the maintainer of this package
+     --node-name NODE_NAME
+                           name of the empty executable
+     --library-name LIBRARY_NAME
+                           name of the empty library

docs/source/editing_python_source.rst

@@ -21,9 +21,10 @@ With the project correctly configured, you can
 1. move to :menuselection:`src --> python_package_with_a_node --> python_package_with_a_node`.
 2. double (left) click :program:`sample_python_node.py` to open the source code, showing the contents of the Node. It is minimal to the point that it doesn't have anything related to :program:`ROS` at all.
 
-.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/sample_python_node.py
+.. literalinclude:: ../../ros2_tutorial_workspace/src/python_package_with_a_node/python_package_with_a_node/sample_python_node.py
    :language: python
    :linenos:
+
 3. right click :program:`sample_python_node.py` and choose :menuselection:`Debug sample_python_node`
 
 It will output in :program:`PyCharm`'s console

docs/source/preamble.rst

@@ -162,7 +162,7 @@ because our file does not have the permission to run as an executable. To give i
 
 and now we can run it properly with
 
-.. code-block:: commandline
+.. code-block:: console
 
    cd ~/ros2_tutorials_preamble/python/minimalist_package/minimalist_package
    ./minimalist_script.py
@@ -448,14 +448,14 @@ For a quick jolt of instant gratification, let's run the tests before we proceed
 
 There are many ways to run tests written with :code:`unittest`. The following will run all tests found in the folder :file:`test`
 
-.. code-block:: commandLine
+.. code-block:: console
 
    cd ~/ros2_tutorials_preamble/python/minimalist_package
    python -m unittest discover -v test
 
 which will output
 
-.. code-block:: commandLine
+.. code-block:: console
    
    test_attribute (test_minimalist_class.TestMinimalistClass) ... ok
    test_get_set_private_attribute (test_minimalist_class.TestMinimalistClass) ... ok

docs/source/preamble/python/python_best_practices.rst

@@ -4,3 +4,4 @@ sphinx-design
 sphinx-rtd-theme
 sphinxext-remoteliteralinclude
 sphinx-book-theme
+sphinxcontrib-globalsubs

docs/source/requirements.txt

@@ -36,22 +36,27 @@ for which the output will be something similar to
 
 .. code :: console
 
-   Summary: 0 packages finished [0.17s]
+   Summary: 0 packages finished [0.08s]
    
 given that we have an empty workspace, no surprise here.
 
 The folders :code:`build`, :code:`install`, and :code:`log` have been generated automatically by :program:`colcon`. The project structure becomes as follows.
 
 .. code-block:: console
-   :emphasize-lines: 3,4,5
+   :emphasize-lines: 2-4
    
    ros2_tutorial_workspace/
-     └── src/
-     └── build/
-     └── install/
-     └── log/
+   |-- build
+   |-- install
+   |-- log
+   `-- src
     
-Inside the :code:`install` folder lie all programs etc generated by the project that can be accessed by the users.     
+Inside the :code:`install` folder lie everything in the project that can be accessed by the users.
+
+.. note::
+
+   An easy way to understand if something is not accessible via :program:`ROS2` commands is if they cannot be found
+   inside your `install` folder.
 
 Do the following just once, so that all terminal windows automatically source this new workspace for you.