Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Under current rosdoc2, several concepts are conflated:
These three concepts were enabled by whether you included a conf.py (either in standard location, or specified by sphinx_sourcedir). There was no way to specify, for example, that my documentation is in docs/ rather than doc/, but I do not include conf.py, and I do not want to override the standard rosdoc2 output.
With this change, you specify the three choices as follows (using the three options above):
This is a behavior change that will affect a few existing packages: those that specified conf.py in a standard doc location (either doc/ or doc/source), but did not specify sphinx_sourcedir. Previously, it was assumed that this was equivalent to specifying sphinx_sourcedir, but that is no longer the case. This PR has two effects on those packages. First, the documentation that previously was the entire rosdoc2 output is now a link under "Documentation", and the root of the rosdoc2 output shows the standard rosdoc2 items, like "Links", "Standard Documents", etc. Second, previously the root of the project was the implied sphinx_sourcedir (either doc/ or doc/source), now the root of the project is the package.xml directory. In many cases this has no effect, but if the supplied documentation has links to generated content, that now needs to be at "../generated" not "generated" so those links fail (but the generated content still shows by default in the standard rosdoc2 links).
I have prepared a full run of rosdoc2 on rolling with this PR applied, that is available at https://prrosdoc2.rosdabbler.com/ I also scanned rolling packages, looking for those that define conf.py. I include a full list later, but here are a few examples;
Packages that previously showed only documentation, now show full rosdoc2 output plus documentation: message_filters, rviz2, image_proc
Packages that have broken API links in their custom documentation: realtime_tools, control_toolbox
A few packages had odd behavior which I investigated and decided were unrelated to this PR:
launch: works in https://docs.ros.org/en/ros2_packages/rolling/api/launch/ but broken at https://prrosdoc2.rosdabbler.com/ This is because the build farm is using Sphinx 7.4.7, with launch showing: "WARNING: The pre-Sphinx 1.0 'intersphinx_mapping' format is deprecated and will be removed in Sphinx 8" rosdabbler uses Sphinx 8, and this is now broken.
cv_bridge: is broken in both (but is fixed in PRs to come, see https://rosdoc2.rosdabbler.com/cv_bridge/)
ur_client_library: shows from June 2024 at https://docs.ros.org/en/ros2_packages/rolling/api/ur_client_library/ but is broken in rosdabbler. I believe this is from a change in the repo, and the current repo would also break in current rosdoc2.
I did not check all of the packages that might be affected, but you are free to do your own checks.
There is a related change in this PR as well. Because essentially package content is copied to the build directory in rosdoc2, there is no need to rename directories as was done previously. I am reverting to using the existing directory names (like 'doc') rather than an artificial name (like 'user_docs'). By preserving the existing doc structure, relative links in user documentation are more likely to work. I am not aware of any current packages that this affects.
In the future, many packages can specify user_doc_dir and have documentation shown that is currently missing. At https://rosdoc2.rosdabbler.com I have included (from future PRs) a curated "correction" file for package rosdoc2.yaml that exposes some of this. See for example rmw_dds_common, tracetools_analysis or rosidl_runtime_c which need user_doc_dir to show their existing documentation.
There are other existing packages that specify sphinx_sourcedir, but would be better off just specifying user_doc_dir. I have not seached for those here.
Affected packages: