From c45320aa23e779264afea3ef75577bb385d88491 Mon Sep 17 00:00:00 2001 From: AJedancov Date: Mon, 10 Aug 2026 10:54:22 +0300 Subject: [PATCH 1/7] docs: describe shared pages usage in Docs Distribution Release Process Signed-off-by: AJedancov --- .gitignore | 3 + .../community/maintainer_docs/docs_release.md | 59 +++++++++++++++++-- mkdocs.yml | 1 + 3 files changed, 58 insertions(+), 5 deletions(-) diff --git a/.gitignore b/.gitignore index 9a01a1bca..613275c04 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,6 @@ __pycache__ macros/cache/* !macros/cache/README.md + +docs/shared/* +!docs/shared/README.md diff --git a/docs/community/maintainer_docs/docs_release.md b/docs/community/maintainer_docs/docs_release.md index d1079a893..6f35ea965 100644 --- a/docs/community/maintainer_docs/docs_release.md +++ b/docs/community/maintainer_docs/docs_release.md @@ -62,25 +62,74 @@ Update link for `edit_uri` key in `mkdocs.yml` configuration file: edit_uri: https://github.com/ros-navigation/docs.nav2.org/blob//docs/ ``` -Update `ros2_distro` variable in `mkdocs.yml`: +Update `ros2_distro` variable and `homepage` parameter in `mkdocs.yml`: ```yaml extra: ros2_distro: "" + homepage: shared/docs.nav2.org/docs/home/ # This is required for point 3.1 ``` -Update `branch` variable in `macros/variables.yml`: +Update `branch` variable and include the new cloning source in `macros/variables.yml`: ```yaml github_repositories: navigation2: - owner: "ros-navigation" + ... branch: "" + ... + + # This is required for point 3.1 + docs.nav2.org: + owner: "ros-navigation" + branch: "rolling" # keep unchanged between distributions + destination_dir: "docs/shared" + data_to_clone: + - "/docs/home" + - "/docs/community" + - "/docs/robots_using" + - "/docs/about_and_contact" ``` ## 3. Update Documentation -### 3.1 Update links +### 3.1 Change directory structure for shared pages + +Delete the following directories that contain content shared across multiple documentation distributions: + +- `/docs/home` +- `/docs/community` +- `/docs/robots_using` +- `/docs/about_and_contact` + +Create new `/docs/shared` directory that will contain shared pages from the `rolling` branch. This serves as the destination for automatically cloned data used in the build process. Create a README.md file to ensure Git will track this empty directory. + +```shell +mkdir -p docs/shared +touch docs/shared/README.md +cat > docs/shared/README.md << EOF +The `docs/shared` directory is used to store cloned data from GitHub. +It contains all common documentation pages that can be shared across multiple distributions. +The content of this directory is taken from the Rolling branch as a main reference. + + +> **Do not delete this file.** The README file keeps the empty directory under Git control. +EOF +``` + +Update paths to the shared directories and files in the parent `docs/.nav.yml` configuration, for example: + +```yaml +# From +- Community: community + +# To: +- Community: shared/docs.nav2.org/docs/community +``` + +Refer to the `.nav.yml` file in previously released versions (e.g., Lyrical, Jazzy) for the complete configuration example. + +### 3.2 Update links - Update all GitHub links to point to new distribution branch where it applies. - Update all links referring to ROS 2 Documentation. @@ -95,7 +144,7 @@ github_repositories: **Lyrical**: [https://docs.ros.org/en/lyrical/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Actions/Understanding-ROS2-Actions.html](https://docs.ros.org/en/lyrical/Tutorials/Beginner-CLI-Tools/Understanding-ROS2-Actions/Understanding-ROS2-Actions.html) -### 3.2 Review tutorials +### 3.3 Review tutorials Review [tutorials][tutorials] for compatibility with the new distribution, including API and behavior changes. diff --git a/mkdocs.yml b/mkdocs.yml index c702f6d78..9bbe1e844 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -137,3 +137,4 @@ exclude_docs: | adaptive_tolerance_goal_checker_illustration.py CancelCoverage.md ComputeCoveragePath.md + shared/README.md From 0cb7d1c1c88fbbabd754d10808fe98b0bf921680 Mon Sep 17 00:00:00 2001 From: AJedancov Date: Tue, 11 Aug 2026 14:27:02 +0300 Subject: [PATCH 2/7] docs: remove homepage from sync process Signed-off-by: AJedancov --- .../community/maintainer_docs/docs_release.md | 25 ++++++++++++++++--- 1 file changed, 21 insertions(+), 4 deletions(-) diff --git a/docs/community/maintainer_docs/docs_release.md b/docs/community/maintainer_docs/docs_release.md index 6f35ea965..7e6f2385f 100644 --- a/docs/community/maintainer_docs/docs_release.md +++ b/docs/community/maintainer_docs/docs_release.md @@ -62,12 +62,11 @@ Update link for `edit_uri` key in `mkdocs.yml` configuration file: edit_uri: https://github.com/ros-navigation/docs.nav2.org/blob//docs/ ``` -Update `ros2_distro` variable and `homepage` parameter in `mkdocs.yml`: +Update `ros2_distro` variable in `mkdocs.yml`: ```yaml extra: ros2_distro: "" - homepage: shared/docs.nav2.org/docs/home/ # This is required for point 3.1 ``` Update `branch` variable and include the new cloning source in `macros/variables.yml`: @@ -85,7 +84,6 @@ github_repositories: branch: "rolling" # keep unchanged between distributions destination_dir: "docs/shared" data_to_clone: - - "/docs/home" - "/docs/community" - "/docs/robots_using" - "/docs/about_and_contact" @@ -97,7 +95,6 @@ github_repositories: Delete the following directories that contain content shared across multiple documentation distributions: -- `/docs/home` - `/docs/community` - `/docs/robots_using` - `/docs/about_and_contact` @@ -129,6 +126,26 @@ Update paths to the shared directories and files in the parent `docs/.nav.yml` c Refer to the `.nav.yml` file in previously released versions (e.g., Lyrical, Jazzy) for the complete configuration example. +Update paths to all robot images and shared page in the `docs/index.md` file, for example: +```html +
+
+ Dexory + ... +``` + +For quick search and replace, the following snippets can be used: + +Search: +``` +href="robots_using/">
- Dexory + Dexory ... ``` @@ -143,7 +181,7 @@ href="robots_using/"> docs/shared/README.md << EOF -The `docs/shared` directory is used to store cloned data from GitHub. -It contains all common documentation pages that can be shared across multiple distributions. -The content of this directory is taken from the Rolling branch as a main reference. - - -> **Do not delete this file.** The README file keeps the empty directory under Git control. -EOF ``` - -Update paths to the shared directories and files in the parent `docs/.nav.yml` configuration. The complete configuration should look as shown below: - -```yaml -nav: - - Home: - # The Home page displays the first two levels of the navigation structure - # with manually specified links to each page for quick access. - # Update this section whenever the documentation directory structure or page order changes. - - index.md - - Getting Started: - - getting_started/index.md - - Quickstart: getting_started/quickstart/quickstart.md - - Build and Install: getting_started/build_and_install/index.md - - Dev Container: getting_started/dev_container/index.md - - Navigation Concepts: getting_started/navigation_concepts/index.md - - Nav2 Behavior Trees: getting_started/nav2_behavior_trees/index.md - - Tutorials: - - tutorials/index.md - - Plugin Tutorials: tutorials/plugin_tutorials/index.md - - General Tutorials: tutorials/general_tutorials/index.md - - Configuration & Development: - - configuration_and_development/index.md - - First-Time Robot Setup Guide: configuration_and_development/first_time_robot_setup_guide/index.md - - Navigation Plugins: configuration_and_development/navigation_plugins.md - - Configuration Guide: configuration_and_development/configuration_guide/index.md - - Tuning Guide: configuration_and_development/tuning_guide.md - - Simple Commander API: configuration_and_development/simple_commander_api/simple_commander_api.md - - Migration Guides: configuration_and_development/migration_guides/index.md - - API Docs: https://api.nav2.org/ - - Community: - - shared/docs.nav2.org/docs/community/index.md - - Getting Involved: shared/docs.nav2.org/docs/community/getting_involved.md - - Maintainer Docs: shared/docs.nav2.org/docs/community/maintainer_docs/index.md - - Roadmaps: shared/docs.nav2.org/docs/community/roadmaps.md - - ROSCon Talks: shared/docs.nav2.org/docs/community/roscon_talks.md - - Robots Using: - - shared/docs.nav2.org/docs/robots_using/index.md - - About & Contact: - - shared/docs.nav2.org/docs/about_and_contact/index.md - - Related Projects: shared/docs.nav2.org/docs/about_and_contact/related_projects.md - - Citations: shared/docs.nav2.org/docs/about_and_contact/citations.md - - Getting Started: getting_started - - Tutorials: tutorials - - Configuration & Development: configuration_and_development - - Community: shared/docs.nav2.org/docs/community - - Robots Using: - - shared/docs.nav2.org/docs/robots_using/index.md - - About & Contact: shared/docs.nav2.org/docs/about_and_contact +# For non-rolling branches only +docs/index.md +docs/community +docs/robots_using +docs/about_and_contact ``` -Update paths to all robot images and shared page in the `docs/index.md` file, for example: -```html -
-
- Dexory - ... -``` +!!! note -For quick search and replace, the following snippets can be used: + If any new common pages are added, add the following metadata to the header of each shared `.md` file in the Rolling branch to use the "Edit this page" function: -Search: -``` -href="robots_using/"> Date: Fri, 14 Aug 2026 09:55:51 +0300 Subject: [PATCH 6/7] docs: supplement note with necessary changes Signed-off-by: AJedancov --- docs/community/maintainer_docs/docs_release.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/community/maintainer_docs/docs_release.md b/docs/community/maintainer_docs/docs_release.md index 9d36cf7b2..5479a3900 100644 --- a/docs/community/maintainer_docs/docs_release.md +++ b/docs/community/maintainer_docs/docs_release.md @@ -134,6 +134,8 @@ docs/about_and_contact --- ``` + Additionally, in the released branch, update the paths to the new common pages or directories as specified in sections [2.3](#23-mkdocs-material) and [3.1](#31-remove-shared-content). + ### 3.2 Update links - Update all GitHub links to point to new distribution branch where it applies. From 9a92c8c6df33f52ba295a216e37506be5f4c8e13 Mon Sep 17 00:00:00 2001 From: AJedancov Date: Fri, 14 Aug 2026 15:07:41 +0300 Subject: [PATCH 7/7] docs: update edit_uri link Signed-off-by: AJedancov --- docs/community/maintainer_docs/docs_release.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/community/maintainer_docs/docs_release.md b/docs/community/maintainer_docs/docs_release.md index 5479a3900..8760d860a 100644 --- a/docs/community/maintainer_docs/docs_release.md +++ b/docs/community/maintainer_docs/docs_release.md @@ -130,7 +130,7 @@ docs/about_and_contact ``` --- - edit_uri: https://github.com/ros-navigation/mkdocs.nav2.org/tree/rolling/docs/ + edit_uri: https://github.com/ros-navigation/docs.nav2.org/tree/rolling/docs/ --- ```