Skip to content
This repository was archived by the owner on Aug 25, 2026. It is now read-only.

feat: sync common pages across distributions - #36

Merged
SteveMacenski merged 3 commits into
jazzyfrom
feat/share-pages--with-home-page
Aug 11, 2026
Merged

feat: sync common pages across distributions #36
SteveMacenski merged 3 commits into
jazzyfrom
feat/share-pages--with-home-page

Conversation

@AJedancov

@AJedancov AJedancov commented Aug 8, 2026

Copy link
Copy Markdown
Collaborator

Basic Info

Info Please fill out this column
Ticket(s) this addresses NA
Does this PR contain AI-generated software? No

Description of contribution in a few bullet points

A commit for Jazzy that automatically syncs common pages from the Rolling branch.
To do this, I used the cloning approach that was implemented previously. I've added an extra parameter destination_dir to specify exactly where to clone the files:

github_repositories:
  navigation2:
  ...
  # TODO: Update directory name 'mkdocs.nav2.org' after documentation release
  mkdocs.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"

Common subpages, together with their assets, are cloned to docs/shared. Since they're in the main /docs directory, they're automatically included in the documentation build.

As this feature will be used in non-rolling branches, some steps must be repeated each time a new version is released:

  1. Completely delete the shared directories (home, community, etc.)
  2. Create a new docs/shared directory and add a README file to it, so that there is at least one file and git can track the empty directory.
  3. Update .gitignore
  4. Exclude the README from build process:
exclude_docs: |
  ...
  shared/README.md
  1. Update the paths to common files in the nav configuration
  2. Update path to the homepage. It is necessary that clicking the main logo in the header opens the right index page.

I think we can combine steps 3 and 4 and move them to the Rolling branch to simplify the process a little. I've added #37 with these steps for the new documentation release process.

I've also slightly changed the structure in Rolling, now the home index and its images are in a separate directory, so that it's easier to reference it when setting up the macro.

Note1: I intentionally didn't use the .nav.yml file in the new home directory. As this plugin doesn't handle relative links correctly (e.g. "../getting_started/index.md"), and these are needed to create the first two levels of the navigation tree.

Note2: Fetching all the graphic materials from GitHub, particularly the videos for the homepage, increases the time taken for the first build. This is unlikely to be a problem for users, as it only happens once and is then used as a cache, but this will also affect the execution time of each CI pipeline.

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
@AJedancov
AJedancov marked this pull request as ready for review August 8, 2026 12:44
@SteveMacenski

SteveMacenski commented Aug 10, 2026

Copy link
Copy Markdown
Member

I assume a similar thing will be applied to lyrical

LGTM, just questions on TODOs if they're meant to stay or not

Comment thread docs/.nav.yml Outdated
Comment thread macros/variables.yml Outdated
Comment thread mkdocs.yml Outdated
Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
@AJedancov
AJedancov force-pushed the feat/share-pages--with-home-page branch from bf146a1 to 13912f4 Compare August 11, 2026 13:00
@AJedancov

Copy link
Copy Markdown
Collaborator Author

I assume a similar thing will be applied to lyrical

Sure, I'll make the same changes there.

I've also removed the homepage from the sync, as mentioned in the main ticket.

@AJedancov

Copy link
Copy Markdown
Collaborator Author

I see the main concept is approved. Do you mind if I merge this now, even if further discussions/changes will follow? This would simplify the testing of such cross-branch changes.

@SteveMacenski
SteveMacenski merged commit 8cb1d58 into jazzy Aug 11, 2026
3 checks passed
@SteveMacenski
SteveMacenski deleted the feat/share-pages--with-home-page branch August 11, 2026 17:56
AJedancov added a commit that referenced this pull request Aug 12, 2026
* feat: implement sharing of common pages across distributions

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* feat: implement synchronization for home page

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* chore: revert homepage synchronisation

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

---------

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
AJedancov added a commit that referenced this pull request Aug 13, 2026
* feat: implement sharing of common pages across distributions

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* feat: implement synchronization for home page

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* chore: revert homepage synchronisation

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

---------

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
AJedancov added a commit that referenced this pull request Aug 14, 2026
* feat: implement sharing of common pages across distributions

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* feat: implement synchronization for home page

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* chore: revert homepage synchronisation

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

---------

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
AJedancov added a commit that referenced this pull request Aug 15, 2026
* feat: implement sharing of common pages across distributions

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* feat: implement synchronization for home page

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* chore: revert homepage synchronisation

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

---------

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
AJedancov added a commit that referenced this pull request Aug 17, 2026
* feat: implement sharing of common pages across distributions

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* feat: implement synchronization for home page

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* chore: revert homepage synchronisation

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

---------

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
AJedancov added a commit that referenced this pull request Aug 18, 2026
* feat: implement sharing of common pages across distributions

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* feat: implement synchronization for home page

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* chore: revert homepage synchronisation

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

---------

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
AJedancov added a commit that referenced this pull request Aug 18, 2026
* feat: implement sharing of common pages across distributions

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* feat: implement synchronization for home page

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* chore: revert homepage synchronisation

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

---------

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
AJedancov added a commit that referenced this pull request Aug 19, 2026
* feat: implement sharing of common pages across distributions

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* feat: implement synchronization for home page

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

* chore: revert homepage synchronisation

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>

---------

Signed-off-by: AJedancov <andrei.jedancov@gmail.com>
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants