It needs to be clearer that the point of this is to point to a non-standard location like docs/source and not to mark that you have customized index.rst and conf.py
Point 2: You should be able to use it without customizing index.rst
Currently, if you specify sphinx_sourcedir but have NOT customized conf.py, it will generate an error. So the program itself seems to have two uses in mind. We already search for conf.py and index.rst and use defaults if missing, we should also do that if the sphinx project is redirected to a different directory.
Point 1: confusing meaning of sphinx_sourcedir
I find six packages in iron currently defining sphinx_sourcedir in rosdoc2.yaml:
rclpy, tf2_ros_py, ffmpeg_image_transport, fuse_doc, ffmpeg_image_transport_tools, event_camera_py
Of these six, three are using it just to point to the default doc/ directory where they have customized index.rst and conf.py:
ffmpeg_image_transport, ffmpeg_image_transport_tools, event_camera_py
It needs to be clearer that the point of this is to point to a non-standard location like docs/source and not to mark that you have customized index.rst and conf.py
Point 2: You should be able to use it without customizing index.rst
Currently, if you specify sphinx_sourcedir but have NOT customized conf.py, it will generate an error. So the program itself seems to have two uses in mind. We already search for conf.py and index.rst and use defaults if missing, we should also do that if the sphinx project is redirected to a different directory.