diff --git a/.gitignore b/.gitignore index 9a01a1bca..13c0b7b72 100644 --- a/.gitignore +++ b/.gitignore @@ -1,6 +1,5 @@ venv site __pycache__ - macros/cache/* !macros/cache/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 000000000..cf199a1a1 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,10 @@ +This directory contains main documentation files for the Nav2 project. To minimize maintenance efforts, some information is automatically synchronized across different distribution branches. The following files and directories are cloned from the `rolling` branch and symlinked to provide a single source for shared documentation: + +- `index.md` +- `images` +- `videos` +- `community` +- `robots_using` +- `about_and_contact` + +To update them, edit only the `rolling` branch. Changes from there will be propagated to all distribution versions. diff --git a/docs/community/maintainer_docs/docs_release.md b/docs/community/maintainer_docs/docs_release.md index d1079a893..8760d860a 100644 --- a/docs/community/maintainer_docs/docs_release.md +++ b/docs/community/maintainer_docs/docs_release.md @@ -69,18 +69,74 @@ extra: ros2_distro: "" ``` -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: "macros/cache" + data_to_clone: + - "/docs/index.md" + - "/docs/images" + - "/docs/videos" + - "/docs/community" + - "/docs/robots_using" + - "/docs/about_and_contact" + symlinks: + "docs/index.md": "macros/cache/docs.nav2.org/docs/index.md" + "docs/images": "macros/cache/docs.nav2.org/docs/images" + "docs/videos": "macros/cache/docs.nav2.org/docs/videos" + "docs/community": "macros/cache/docs.nav2.org/docs/community" + "docs/robots_using": "macros/cache/docs.nav2.org/docs/robots_using" + "docs/about_and_contact": "macros/cache/docs.nav2.org/docs/about_and_contact" ``` ## 3. Update Documentation -### 3.1 Update links +### 3.1 Remove shared content + +Delete the following directories and files that are shared across multiple documentation distributions: + +- `docs/index.md` +- `docs/images` +- `docs/videos` +- `docs/community` +- `docs/robots_using` +- `docs/about_and_contact` + +Include them in `.gitignore`: + +``` +# For non-rolling branches only +docs/index.md +docs/images +docs/videos +docs/community +docs/robots_using +docs/about_and_contact +``` + +!!! note + + 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: + + ``` + --- + edit_uri: https://github.com/ros-navigation/docs.nav2.org/tree/rolling/docs/ + --- + ``` + + 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. - Update all links referring to ROS 2 Documentation. @@ -95,7 +151,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..8012ce403 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -137,3 +137,4 @@ exclude_docs: | adaptive_tolerance_goal_checker_illustration.py CancelCoverage.md ComputeCoveragePath.md + README.md