change docs file structure to work with recent rosdoc2

[ottojo]

Description

This moves the sphinx docs sources one directory up, as expected by rosdoc2. Furthermore, the sphinx sourcedir is configured in rosdoc2.yaml, which is how to tell rosdoc2 to use the existing index.rst instead of wrapping it (https://github.com/ros-infrastructure/rosdoc2/blob/main/doc/index.rst.md).
I have added toctree entries for the autogenerated documentation elements by rosdoc2.

This should also fix ros2/ros2_documentation#6042

Is this user-facing behavior change?

Yes, the documentation page will change. It seems however (as apparent in the issue above), that the resulting link to architecture.html was changed inadvertently at some point. This reverts it back to the original link.

Did you use Generative AI?

No.

Additional info

Needs @Mergifyio backport humble jazzy rolling

[fujitatomoya]

@ottojo my understanding is that this PR replaces ros2/ros2_documentation#6043, right? IMO this fix makes much better than ros2/ros2_documentation#6043.

[ottojo]

@ottojo my understanding is that this PR replaces ros2/ros2_documentation#6043, right? IMO this fix makes much better than ros2/ros2_documentation#6043.

yes, this is intended to replace 6043

[ahcorde]

I can see this error

WARNING: toctree contains reference to nonexisting document '__ros_package_dependencies' [toc.not_readable]

[ottojo]

I can't reproduce this, is this on the buildfarm or locally for you? This probably happens with a (perhaps just slightly) out of date rosdoc2, as this only got merged recently: ros-infrastructure/rosdoc2#205

[ahcorde]

I'm running version rosdoc2 0.2.2.dev0, I used a virtual env to install rosdoc2 with the latest changes but I can't see this directory.

I'm using this cmd:

rosdoc2 build   --package-path ./src/ros2/launch/launch

[ottojo]

i could reproduce the same warning with rosdoc2 installed via the python3-rosdoc2 apt package on kilted (after making this change in the rosdoc2 yaml, which is not required in a more recent version).

diff --git a/launch/rosdoc2.yaml b/launch/rosdoc2.yaml
index d2f5855..c243fe9 100644
--- a/launch/rosdoc2.yaml
+++ b/launch/rosdoc2.yaml
@@ -3,4 +3,4 @@ version: 1
 ---
 settings: {}
 builders:
-  - sphinx: { sphinx_sourcedir: "doc" }
+  - sphinx: { name: "launch", output_dir: "", sphinx_sourcedir: "doc" }

I'm not sure how to proceed here, to me this looks to me like a rosdoc2 version issue, unfortunately the version has not been bumped in 2 years despite significant changes (https://github.com/ros-infrastructure/rosdoc2/blob/main/rosdoc2/__init__.py#L15)

[fujitatomoya]

@ottojo can you address the comments?

[ottojo]

@fujitatomoya I have applied the suggestions, and added a redirect since the link change in the ros2-docs got merged in the meantime, so both versions stay working.

I'm not sure how to proceed with the warning seen by @ahcorde , maybe someone else could verify if this is or isn't an issue, or maybe it's possible somehow to run the buildfarm doc job for this PR to check if that works?