3di TOC restructuring

[dmarshant]

Description

This pull request is only a DRAFT because cross-links have not been updated, nor redirects. This request is for others to view the new TOC structure, and to flag up any pages that are not in the correct sections.

Fixes #6825

Did you use Generative AI?

No

Additional Information

Documentation updates from 3di Information Solutions, agreed with Geoff and Tully.

[kscottz]

@dmarshant I'm not sure why CI is not running on this. I suspect it is related to the recent Github outage.

As I am sure you are aware, there are still a lot of issues that need to be resolved (at least that's what I saw when I built this PR locally). You're also going to need to pull in our recent changes for the Lyrical release.

Given the size of this change I think what we might want to do is to approach it from WYSIWYG approach where we look at the final generated HTML instead of the RST files. We might also want to divide and conquer across the maintainers. @ahcorde, @fujitatomoya, @christophebedard I would be interested in hearing your opinions here. It would be really hard to put this together as a series of smaller PRs so we may just want to rip the band-aid off all at once.

One thing we're going to need to be cognizant of is what this change will do any inbound links. I am a bit concerned we're going to break documentation that's down stream of the canonical docs. If we only target these changes to Lyrical and Rolling, and avoid all other back ports that might lessen that problem. If that's the case, sooner is probably better even if it is imperfect.

Now that I've written this all out, I am starting to wonder if we want to accelerate things here even if it means a bumpy road for a few months.

[dmarshant]

Thanks @kscottz ! I've now updated all of the internal links (including images) and have added redirects to all of the files based on their location prior to my rearranging. I've not been able to get make lint work as I'm currently on Windows, but the only errors in the make build are files which aren't included in any TOC (pages which also don't seem to be included in the current docs on the website)

[tfoote]

I added a few fixups to the linter build and spellcheck paths.

There appears to have been a bunch of carriage returns added to every new line. As well as some whitespace and removed trailing newlines which are all failing linting.

With this being just a reorg we'll probably want to just check the results manually. I think this will build the html and upload it here to the issue. However it will only run the test build after the linters are passing. So we'll need to fix that to see the results.

[tfoote]

I've reviewed a local copy and the one thing that stood out to me (and I noticed because of fixing the paths above is that the Distributions list is nested under Getting Started, I think that would be better under the Frameworks section or somewhere else. That level of detail is a strong external reference and is too deep for people who are actually getting started.

[3di-for-openrobotics]

@kscottz and @tfoote please see updated PR #6898 (recreated to change base repo)

[dmarshant]

Closing this pull request -- recreated with a different base repo in #6898