Change "Guides" to "How-to Guides" (ros2#1972)

* Change "Guides" to "How-to Guides" Signed-off-by: Audrow Nash <[email protected]> * Add redirects Signed-off-by: Audrow Nash <[email protected]>
CursedRock17 · Sep 24, 2021 · 9c5a8c9 · 9c5a8c9
1 parent 24bcbb3
commit 9c5a8c9
Show file tree

Hide file tree

Showing 53 changed files with 117 additions and 79 deletions.
diff --git a/rosindex.yml b/rosindex.yml
@@ -9,7 +9,7 @@ index_pattern:
   - index.rst
   - Installation.rst
   - Tutorials.rst
-  - Guides.rst
+  - How-To-Guides.rst
   - Concepts.rst
   - Contributing.rst
   - Releases.rst

diff --git a/source/Concepts/About-Build-System.rst b/source/Concepts/About-Build-System.rst
@@ -98,7 +98,7 @@ Here a list of the |packages| in the repository along with a short description:
 -  ``ament_cmake_python``
 
    - provides CMake functions for |packages| that contain Python code
-   - see the `ament_cmake_python user documentation <../Guides/Ament-CMake-Python-Documentation>`__
+   - see the `ament_cmake_python user documentation <../How-To-Guides/Ament-CMake-Python-Documentation>`__
 
 -  ``ament_cmake_test``
 

diff --git a/source/Concepts/About-Cross-Compilation.rst b/source/Concepts/About-Cross-Compilation.rst
@@ -27,4 +27,4 @@ It is a Python script that compiles ROS 2 source files for supported target arch
 Detailed design of the tool can be found on `ROS 2 design <https://design.ros2.org/articles/cc_build_tools.html>`__.
 Instructions to use the tool are in the `cross_compile package <https://github.com/ros-tooling/cross_compile>`__.
 
-If you are using an older version, please follow the `cross-compilation guide <../Guides/Cross-compilation>`.
+If you are using an older version, please follow the `cross-compilation guide <../How-To-Guides/Cross-compilation>`.
diff --git a/source/Concepts/About-Different-Middleware-Vendors.rst b/source/Concepts/About-Different-Middleware-Vendors.rst
@@ -43,7 +43,7 @@ Supported RMW implementations
      - ``rmw_connextdds``
      - Full support. Support included in binaries, but Connext installed separately.
 
-For practical information on working with multiple RMW implementations, see the `"Working with multiple RMW implementations" <../Guides/Working-with-multiple-RMW-implementations>` tutorial.
+For practical information on working with multiple RMW implementations, see the `"Working with multiple RMW implementations" <../How-To-Guides/Working-with-multiple-RMW-implementations>` tutorial.
 
 Multiple RMW implementations
 ----------------------------
@@ -79,4 +79,4 @@ The implementation identifier is the name of the ROS package that provides the R
 For example, if both ``rmw_fastrtps_cpp`` and ``rmw_connextdds`` ROS packages are installed, ``rmw_connextdds`` would be the default.
 If ``rmw_cyclonedds_cpp`` is ever installed, it would be the default.
 
-See the `guide <../Guides/Working-with-multiple-RMW-implementations>` for how to specify which RMW implementation is to be used when running the ROS 2 examples.
+See the `guide <../How-To-Guides/Working-with-multiple-RMW-implementations>` for how to specify which RMW implementation is to be used when running the ROS 2 examples.
diff --git a/source/Concepts/About-RQt.rst b/source/Concepts/About-RQt.rst
@@ -56,7 +56,7 @@ Installing From Debian
 Building From Source
 ^^^^^^^^^^^^^^^^^^^^
 
-See `Building RQt from Source <../Guides/RQt-Source-Install>`.
+See `Building RQt from Source <../How-To-Guides/RQt-Source-Install>`.
 
 RQt Components Structure
 ------------------------

diff --git a/source/Contributing/Developer-Guide.rst b/source/Contributing/Developer-Guide.rst
@@ -285,7 +285,7 @@ When filing an issue please make sure to:
   - Upgrading to the latest version of the code, which may include bug fixes that have not been released yet.
     See `this section <building-from-source>` and follow the instructions to get the "master" branches.
   - Trying with a different RMW implementation.
-    See `this page <../Guides/Working-with-multiple-RMW-implementations>` for how to do that.
+    See `this page <../How-To-Guides/Working-with-multiple-RMW-implementations>` for how to do that.
 
 Pull requests
 ^^^^^^^^^^^^^

diff --git a/source/Contributing/Migration-Guide.rst b/source/Contributing/Migration-Guide.rst
@@ -415,7 +415,7 @@ Launch files
 ------------
 
 While launch files in ROS 1 are always specified using `.xml <https://wiki.ros.org/roslaunch/XML>`__ files, ROS 2 supports Python scripts to enable more flexibility (see `launch package <https://github.com/ros2/launch/tree/master/launch>`__) as well as XML and YAML files.
-See `separate tutorial <../Guides/Launch-files-migration-guide>` on migrating launch files from ROS 1 to ROS 2.
+See `separate tutorial <../How-To-Guides/Launch-files-migration-guide>` on migrating launch files from ROS 1 to ROS 2.
 
 Example: Converting an existing ROS 1 package to use ROS 2
 ----------------------------------------------------------

diff --git a/source/Features.rst b/source/Features.rst
@@ -17,7 +17,7 @@ For planned future development, see the :ref:`Roadmap <Roadmap>`.
      - `Article <https://design.ros2.org/articles/ros_on_dds.html>`__
      -
    * - Support for `multiple DDS implementations <Concepts/About-Different-Middleware-Vendors>`, chosen at runtime
-     - `Concept <Concepts/About-Different-Middleware-Vendors>`, `Guide <Guides/Working-with-multiple-RMW-implementations>`
+     - `Concept <Concepts/About-Different-Middleware-Vendors>`, `How-to Guide <How-To-Guides/Working-with-multiple-RMW-implementations>`
      - Currently Eclipse Cyclone DDS, eProsima Fast DDS, and RTI Connext DDS are fully supported.
    * - Common core client library that is wrapped by language-specific libraries
      - `Details <Concepts/About-ROS-2-Client-Libraries>`
@@ -62,7 +62,7 @@ For planned future development, see the :ref:`Roadmap <Roadmap>`.
      - `Article <https://design.ros2.org/articles/topic_and_service_names.html>`__
      -
    * - Static remapping of ROS names
-     - `Guide <Guides/Node-arguments>`
+     - `How-to Guide <How-To-Guides/Node-arguments>`
      -
    * - Demos of an all-ROS 2 mobile robot
      - `Demo <https://github.com/ros2/turtlebot2_demo>`__

diff --git a/source/Guides.rst b/source/Guides.rst
diff --git a/source/How-To-Guides.rst b/source/How-To-Guides.rst
@@ -0,0 +1,46 @@
+.. redirect-from::
+
+  Guides
+
+.. _How-to Guides:
+
+How-to Guides
+=============
+
+How-to Guides provide direct and modular answers to "How-to" questions regarding key aspects of ROS 2.
+They contain succinct steps to help you accomplish important tasks quickly.
+
+How-to Guides are meant for users who already have some knowledge of ROS 2 and just want to find out how to implement something specific.
+They will not go in-depth by providing background information or teaching how a concept ties into the greater ROS 2 ecosystem.
+
+If you are new and looking to learn the ropes, start with the :ref:`Tutorials <Tutorials>` for a more well-rounded progression through ROS 2.
+
+
+
+.. toctree::
+   :maxdepth: 1
+
+   How-To-Guides/Installation-Troubleshooting
+   How-To-Guides/Developing-a-ROS-2-Package
+   How-To-Guides/Ament-CMake-Documentation
+   How-To-Guides/Ament-CMake-Python-Documentation
+   How-To-Guides/Launch-files-migration-guide
+   How-To-Guides/Launch-file-different-formats
+   How-To-Guides/Parameters-YAML-files-migration-guide
+   How-To-Guides/Node-arguments
+   How-To-Guides/Sync-Vs-Async
+   How-To-Guides/DDS-tuning
+   How-To-Guides/Overriding-QoS-Policies-For-Recording-And-Playback
+   How-To-Guides/Working-with-multiple-RMW-implementations
+   How-To-Guides/Cross-compilation
+   How-To-Guides/Releasing-a-ROS-2-package-with-bloom
+   How-To-Guides/Using-Python-Packages
+   How-To-Guides/RQt-Port-Plugin-Windows
+   How-To-Guides/Run-2-nodes-in-single-or-separate-docker-containers
+   How-To-Guides/Package-maintainer-guide
+   How-To-Guides/Building-a-Custom-Debian-Package
+
+.. toctree::
+  :hidden:
+
+  How-To-Guides/RQt-Source-Install
diff --git a/source/Guides/Ament-CMake-Documentation.rst → ...w-To-Guides/Ament-CMake-Documentation.rst b/source/Guides/Ament-CMake-Documentation.rst → ...w-To-Guides/Ament-CMake-Documentation.rst
@@ -1,5 +1,6 @@
 .. redirect-from::
 
+  Guides/Ament-CMake-Documentation
   Tutorials/Ament-CMake-Documentation
 
 ament_cmake user documentation

diff --git a/...ides/Ament-CMake-Python-Documentation.rst → ...ides/Ament-CMake-Python-Documentation.rst b/...ides/Ament-CMake-Python-Documentation.rst → ...ides/Ament-CMake-Python-Documentation.rst
@@ -1,3 +1,7 @@
+.. redirect-from::
+
+  Guides/Ament-CMake-Python-Documentation
+
 ament_cmake_python user documentation
 =====================================
 

diff --git a/...ides/Building-a-Custom-Debian-Package.rst → ...ides/Building-a-Custom-Debian-Package.rst b/...ides/Building-a-Custom-Debian-Package.rst → ...ides/Building-a-Custom-Debian-Package.rst
@@ -1,3 +1,7 @@
+.. redirect-from::
+
+  Guides/Building-a-Custom-Debian-Package
+
 Building a custom Debian package
 ================================
 

diff --git a/source/Guides/Cross-compilation.rst → source/How-To-Guides/Cross-compilation.rst b/source/Guides/Cross-compilation.rst → source/How-To-Guides/Cross-compilation.rst
@@ -1,5 +1,6 @@
 .. redirect-from::
 
+  Guides/Cross-compilation
   Tutorials/Cross-compilation
 
 Cross-compilation

diff --git a/source/Guides/DDS-tuning.rst → source/How-To-Guides/DDS-tuning.rst b/source/Guides/DDS-tuning.rst → source/How-To-Guides/DDS-tuning.rst
@@ -1,5 +1,6 @@
 .. redirect-from::
 
+  Guides/DDS-tuning
   Troubleshooting/DDS-tuning
 
 DDS tuning information

diff --git a/source/Guides/Developing-a-ROS-2-Package.rst → ...-To-Guides/Developing-a-ROS-2-Package.rst b/source/Guides/Developing-a-ROS-2-Package.rst → ...-To-Guides/Developing-a-ROS-2-Package.rst
@@ -1,6 +1,7 @@
 .. redirect-from::
 
     Developing-a-ROS-2-Package
+    Guides/Developing-a-ROS-2-Package
     Tutorials/Developing-a-ROS-2-Package
 
 Developing a ROS 2 package

diff --git a/...e/Guides/Installation-Troubleshooting.rst → ...o-Guides/Installation-Troubleshooting.rst b/...e/Guides/Installation-Troubleshooting.rst → ...o-Guides/Installation-Troubleshooting.rst
@@ -1,5 +1,6 @@
 .. redirect-from::
 
+  Guides/Installation-Troubleshooting
   Troubleshooting/Installation-Troubleshooting
 
 Installation troubleshooting

diff --git a/.../Guides/Launch-file-different-formats.rst → ...-Guides/Launch-file-different-formats.rst b/.../Guides/Launch-file-different-formats.rst → ...-Guides/Launch-file-different-formats.rst
@@ -1,3 +1,7 @@
+.. redirect-from::
+
+  Guides/Launch-file-different-formats
+
 Using Python, XML, and YAML for ROS 2 Launch Files
 ==================================================
 

diff --git a/...e/Guides/Launch-files-migration-guide.rst → ...o-Guides/Launch-files-migration-guide.rst b/...e/Guides/Launch-files-migration-guide.rst → ...o-Guides/Launch-files-migration-guide.rst
@@ -1,5 +1,6 @@
 .. redirect-from::
 
+  Guides/Launch-files-migration-guide
   Tutorials/Launch-files-migration-guide
 
 .. _MigratingLaunch:

diff --git a/source/Guides/Node-arguments.rst → source/How-To-Guides/Node-arguments.rst b/source/Guides/Node-arguments.rst → source/How-To-Guides/Node-arguments.rst
@@ -1,6 +1,7 @@
 .. redirect-from::
 
     Node-arguments
+    Guides/Node-arguments
     Tutorials/Node-arguments
 
 Passing ROS arguments to nodes via the command-line

diff --git a/...S-Policies-For-Recording-And-Playback.rst → ...S-Policies-For-Recording-And-Playback.rst b/...S-Policies-For-Recording-And-Playback.rst → ...S-Policies-For-Recording-And-Playback.rst
@@ -1,5 +1,6 @@
 .. redirect-from::
 
+  Guides/Overriding-QoS-Policies-For-Recording-And-Playback
   Tutorials/Ros2bag/Overriding-QoS-Policies-For-Recording-And-Playback
 
 .. _ROS2Bag-QoS-Override:

diff --git a/source/Guides/Package-maintainer-guide.rst → ...ow-To-Guides/Package-maintainer-guide.rst b/source/Guides/Package-maintainer-guide.rst → ...ow-To-Guides/Package-maintainer-guide.rst
@@ -1,3 +1,7 @@
+.. redirect-from::
+
+  Guides/Package-maintainer-guide
+
 ROS 2 Package Maintainer Guide
 ==============================
 

diff --git a/...Parameters-YAML-files-migration-guide.rst → ...Parameters-YAML-files-migration-guide.rst b/...Parameters-YAML-files-migration-guide.rst → ...Parameters-YAML-files-migration-guide.rst
@@ -1,5 +1,6 @@
 .. redirect-from::
 
+  Guides/Parameters-YAML-files-migration-guide
   Tutorials/Parameters-YAML-files-migration-guide
 
 .. _yaml-ros1-ros2:

diff --git a/source/Guides/RQt-Port-Plugin-Windows.rst → ...How-To-Guides/RQt-Port-Plugin-Windows.rst b/source/Guides/RQt-Port-Plugin-Windows.rst → ...How-To-Guides/RQt-Port-Plugin-Windows.rst
@@ -1,6 +1,7 @@
 .. redirect-from::
 
     RQt-Port-Plugin-Windows
+    Guides/RQt-Port-Plugin-Windows
     Tutorials/RQt-Port-Plugin-Windows
 
 Porting RQt plugins to Windows

diff --git a/source/Guides/RQt-Source-Install-MacOS.rst → ...ow-To-Guides/RQt-Source-Install-MacOS.rst b/source/Guides/RQt-Source-Install-MacOS.rst → ...ow-To-Guides/RQt-Source-Install-MacOS.rst
@@ -1,6 +1,7 @@
 .. redirect-from::
 
     RQt-Source-Install-MacOS
+    Guides/RQt-Source-Install-MacOS
 
 Building RQt from source on macOS
 =================================

diff --git a/...e/Guides/RQt-Source-Install-Windows10.rst → ...o-Guides/RQt-Source-Install-Windows10.rst b/...e/Guides/RQt-Source-Install-Windows10.rst → ...o-Guides/RQt-Source-Install-Windows10.rst
@@ -1,6 +1,7 @@
 .. redirect-from::
 
     RQt-Source-Install-Windows10
+    Guides/RQt-Source-Install-Windows10
 
 Building RQt from source on Windows 10
 ======================================

diff --git a/source/Guides/RQt-Source-Install.rst → source/How-To-Guides/RQt-Source-Install.rst b/source/Guides/RQt-Source-Install.rst → source/How-To-Guides/RQt-Source-Install.rst
@@ -1,6 +1,7 @@
 .. redirect-from::
 
     RQt-Source-Install
+    Guides/RQt-Source-Install
 
 Building RQt from source
 ========================

diff --git a/.../Releasing-a-ROS-2-package-with-bloom.rst → .../Releasing-a-ROS-2-package-with-bloom.rst b/.../Releasing-a-ROS-2-package-with-bloom.rst → .../Releasing-a-ROS-2-package-with-bloom.rst
@@ -1,6 +1,7 @@
 .. redirect-from::
 
     Releasing-a-ROS-2-package-with-bloom
+    Guides/Releasing-a-ROS-2-package-with-bloom
     Tutorials/Releasing-a-ROS-2-package-with-bloom
 
 Releasing a ROS 2 package with bloom

diff --git a/...-single-or-separate-docker-containers.rst → ...-single-or-separate-docker-containers.rst b/...-single-or-separate-docker-containers.rst → ...-single-or-separate-docker-containers.rst
@@ -2,6 +2,7 @@
 
     Tutorials/Run-2-nodes-in-a-single-docker-container
     Tutorials/Run-2-nodes-in-two-separate-docker-containers
+    Guides/Run-2-nodes-in-two-separate-docker-containers
 
 Running ROS 2 nodes in Docker [community-contributed]
 =====================================================

diff --git a/source/Guides/Sync-Vs-Async.rst → source/How-To-Guides/Sync-Vs-Async.rst b/source/Guides/Sync-Vs-Async.rst → source/How-To-Guides/Sync-Vs-Async.rst
@@ -1,5 +1,6 @@
 .. redirect-from::
 
+  Guides/Sync-Vs-Async
   Tutorials/Sync-Vs-Async
 
 .. _SyncAsync:

diff --git a/source/Guides/Using-Python-Packages.rst → ...e/How-To-Guides/Using-Python-Packages.rst b/source/Guides/Using-Python-Packages.rst → ...e/How-To-Guides/Using-Python-Packages.rst
@@ -1,5 +1,6 @@
 .. redirect-from::
 
+  Guides/Using-Python-Packages
   Tutorials/Using-Python-Packages
 
 .. _PythonPackages:

diff --git a/...ing-with-multiple-RMW-implementations.rst → ...ing-with-multiple-RMW-implementations.rst b/...ing-with-multiple-RMW-implementations.rst → ...ing-with-multiple-RMW-implementations.rst
@@ -1,6 +1,7 @@
 .. redirect-from::
 
     Working-with-multiple-RMW-implementations
+    Guides/Working-with-multiple-RMW-implementations
     Tutorials/Working-with-multiple-RMW-implementations
 
 Working with multiple ROS 2 middleware implementations

diff --git a/source/Installation/DDS-Implementations.rst b/source/Installation/DDS-Implementations.rst
@@ -21,7 +21,7 @@ Since Eloquent, both Fast DDS and Cyclone DDS are bundled, but Fast DDS is still
 If you would like to use one of the other vendors you will need to install their software separately before building.
 The ROS 2 build will automatically build support for vendors that have been installed and sourced correctly.
 
-Once you've installed a new DDS vendor, you can change the vendor used at runtime: `Working with Multiple RMW Implementations </Guides/Working-with-multiple-RMW-implementations>`.
+Once you've installed a new DDS vendor, you can change the vendor used at runtime: `Working with Multiple RMW Implementations </How-To-Guides/Working-with-multiple-RMW-implementations>`.
 
 Detailed instructions for installing other DDS vendors are provided below.
 

diff --git a/source/Installation/DDS-Implementations/Working-with-Eclipse-CycloneDDS.rst b/source/Installation/DDS-Implementations/Working-with-Eclipse-CycloneDDS.rst
@@ -59,7 +59,7 @@ Switch from other rmw to rmw_cyclonedds by specifying the environment variable.
 
    export RMW_IMPLEMENTATION=rmw_cyclonedds_cpp
 
-See also: `Working with multiple RMW implementations <../../Guides/Working-with-multiple-RMW-implementations>`
+See also: `Working with multiple RMW implementations <../../How-To-Guides/Working-with-multiple-RMW-implementations>`
 
 Run the talker and listener
 ---------------------------

diff --git a/source/Installation/DDS-Implementations/Working-with-eProsima-Fast-DDS.rst b/source/Installation/DDS-Implementations/Working-with-eProsima-Fast-DDS.rst
@@ -54,7 +54,7 @@ The eProsima Fast DDS RMW can be selected by specifying the environment variable
 
    export RMW_IMPLEMENTATION=rmw_fastrtps_cpp
 
-See also: `Working with multiple RMW implementations <../../Guides/Working-with-multiple-RMW-implementations>`
+See also: `Working with multiple RMW implementations <../../How-To-Guides/Working-with-multiple-RMW-implementations>`
 
 Run the talker and listener
 ---------------------------

diff --git a/source/Installation/RHEL-Development-Setup.rst b/source/Installation/RHEL-Development-Setup.rst
@@ -165,7 +165,7 @@ The ROS 1 bridge can connect topics from ROS 1 to ROS 2 and vice-versa. See the
 Additional RMW implementations (optional)
 -----------------------------------------
 The default middleware that ROS 2 uses is ``Cyclone DDS``, but the middleware (RMW) can be replaced at runtime.
-See the `guide <../Guides/Working-with-multiple-RMW-implementations>` on how to work with multiple RMWs.
+See the `guide <../How-To-Guides/Working-with-multiple-RMW-implementations>` on how to work with multiple RMWs.
 
 Alternate compilers
 -------------------

diff --git a/source/Installation/RHEL-Install-Binary.rst b/source/Installation/RHEL-Install-Binary.rst
@@ -125,12 +125,12 @@ Continue with the `tutorials and demos <../Tutorials>` to configure your environ
 Additional RMW implementations (optional)
 -----------------------------------------
 The default middleware that ROS 2 uses is ``Cyclone DDS``, but the middleware (RMW) can be replaced at runtime.
-See the `guide <../Guides/Working-with-multiple-RMW-implementations>` on how to work with multiple RMWs.
+See the `guide <../How-To-Guides/Working-with-multiple-RMW-implementations>` on how to work with multiple RMWs.
 
 Troubleshooting
 ---------------
 
-Troubleshooting techniques can be found `here <../Guides/Installation-Troubleshooting>`.
+Troubleshooting techniques can be found `here <../How-To-Guides/Installation-Troubleshooting>`.
 
 Uninstall
 ---------