3di TOC restructure (backport #6898)

[ahcorde]

Backport of #6898 to the lyrical branch, squashing all 40 commits of the PR into a single commit.

Description

Manually backport #6898

Did you use Generative AI?

Claude Opus 4.7

[github-actions]

HTML artifacts: https://github.com/ros2/ros2_documentation/actions/runs/30103237599/artifacts/8600760101.

To view the resulting site:

1. Click on the above link to download the artifacts archive
2. Extract it
3. Open html-artifacts-6998/index.html in your favorite browser

[ahcorde]

@kscottz I backported this to lyrical as requested in the original PR, do you mind to take a look. This is a big change

[kscottz]

Just finally getting a chance to look at this. Am I fair to assume this is even with rolling?

[kscottz]

Woof. There are a lot of things that could be better here. There are a lot of articles that seem really out of place or shoe horned into categories. I started trying to call them out but that doesn't seem particularly useful.

I don't think forward porting from Lyrical is the right the answer here. The logical solution would be to just force this through and fix the issues on rolling. @fujitatomoya @ahcorde what are your thoughts here?

[RachelPotts]

@kscottz About the articles that seem out of place: please do let us know about them, and we'll address quickly. For info, we're already working through this to-do list (some relate to our previous discussions, where we've now also had input from Geoff too). These will start coming though as individual PRs soon.

[fujitatomoya]

@kscottz i agree with you, i say let's not do backport any of these changes. we can revisit and backport the fixes if needed after certain soaking time in rolling documentation. (or maybe this documentation facelist is only for rolling.)

[fujitatomoya]

@kscottz i agree with you, i say let's not do backport any of these changes. we can revisit and backport the fixes if needed after certain soaking time in rolling documentation. (or maybe this documentation facelist is only for rolling.)

i need to change my mind here. see #7031 (comment)

for the maintainability mostly, i think we need to backport doc structure change to all the downstream branches including this one. otherwise, it will be really hard to backport the doc enhancement to the downstream distros.

CC: @kscottz @gbiggs @mjcarroll @ahcorde

[fujitatomoya]

CC: @3di-for-openrobotics

[gbiggs]

We had already agreed to backport the documentation overhaul to Lyrical, but no further. That would require manual backporting of changes that are also relevant to Humble and Kilted, but the first is only around for another 3 months and the second for 9 months. Jazzy could be worth backporting to as it's around until 2029. The number of changes that come in, separate from the 3di effort, that must be backported to Humble and Kilted is low, so I do not think the effort to do those backports manually over the next few months is likely to be too high.

Alternatively, we could backport all the way to Humble now, but that's a significant effort for two distributions that have only a short lifetime left.

If we don't backport, we're just going to have to deal with this anyway in May 2027, when Makoa is released. Makoa's documentation will be based of Rolling, which means any changes done then would need manual backporting to both Jazzy and Lyrical - which I think would be more effort then backporting the 3di work to Jazzy and Lyrical now.

[gbiggs]

Woof. There are a lot of things that could be better here. There are a lot of articles that seem really out of place or shoe horned into categories. I started trying to call them out but that doesn't seem particularly useful.

@kscottz The ToC reorganisation has already gone through several rounds of review at several levels and is the result of considerable discussion over more than six months. The ROS PMC was also asked for input a few months ago. It's not perfect yet but we decided that it's close enough to get the changes in and fix any oddities in follow-up PRs. If you see articles that should be elsewhere, then please identify them so they can be fixed in Rolling, and backported if necessary. A backport PR is not the place to be debating the original changes that were made to Rolling.