Published API documentation

[adamsj-ros]

Bug report

Required Info:

• Operating System:
  • any
• Installation type:
  • any
• Version or commit hash:
  • foxy branch
• DDS implementation:
  • N/A
• Client library (if applicable):
  • N/A

Steps to reproduce issue

Where is the published API for launch_ros? I see this post on answers which could be answered by a published API. I see that there are API doc syntax available. After searching, Google, index.ros.org and answers.ros.org, I can't seem to find this APIs publication. I think it should probably reside on index.ros.org with the rest of the APIs. Maybe it's not the appropriate place. I'm open but I think it's too hard to find at the moment.

Additional information

---

Feature request

Feature description

Implementation considerations

[hidmic]

Where is the published API for launch_ros?

@adamsj-ros To the best of my knowledge, we don't currently host generated documentation anywhere, unfortunately. A lot of work has gone into http://docs.ros.org/ recently, but API documentation for pure Python packages isn't there yet.

[adamsj-ros]

we don't currently host generated documentation anywhere

I didn't notice a makefile for generating Sphinx documentation. How are the docs manually generated? Maybe that could go into a new README.rst?

[peredwardsson]

Any update on this? Quite hard to learn how this package works without being able to read an API. Examples are only good for getting started.

[acarrillo]

+1 for published documentation, please! The robotics community at large is still on-ramping into ROS 2. The Python launch syntax is very complicated; If it's going to win favor over the XML declarative style launch file, this is an easy way to lower the friction.

I could be naive, but the 'independent' class of API docs on docs.ros.org seemed a bit friendly to independent, pure Python packages, like rosdep https://docs.ros.org/en/independent/api/rosdep/html/

Outside of that, is there a stopgap solution to publishing the docs for now in an out-of-band way, like static S3 hosting or GitHub Pages?

[acarrillo]

I didn't notice a makefile for generating Sphinx documentation. How are the docs manually generated? Maybe that could go into a new README.rst?

@adamsj-ros , it's kind of a hack, but I was able to generate some quick docs from the codebase with pdoc3:

$ git clone [email protected]:ros2/launch_ros.git
$ cd launch_ros/launch_ros
$ pip3 install pdoc3
$ python3 -m pdoc3 --html .
$ cd html/ros2launch
$ python3 -m http.server # hosts HTTP file server at http://localhost:8000

I got a pretty neat fast result:

[rkent]

Update on this:

The API documentation for python in general has been out for about a year now, but unfortunately rosdoc2 fails on launch_ros, so no useful output is being generated.

The errors are all variations of:

WARNING: autodoc: failed to import module 'actions.set_parameters_from_file' from module 'launch_ros'; the following exception was raised:
Traceback (most recent call last):
  File "/workspace/venv/lib/python3.10/site-packages/sphinx/ext/autodoc/importer.py", line 143, in import_module
    return importlib.import_module(modname)
  File "/usr/lib/python3.10/importlib/__init__.py", line 126, in import_module
    return _bootstrap._gcd_import(name[level:], package, level)
  File "<frozen importlib._bootstrap>", line 1050, in _gcd_import
  File "<frozen importlib._bootstrap>", line 1027, in _find_and_load
  File "<frozen importlib._bootstrap>", line 1006, in _find_and_load_unlocked
  File "<frozen importlib._bootstrap>", line 688, in _load_unlocked
  File "<frozen importlib._bootstrap_external>", line 883, in exec_module
  File "<frozen importlib._bootstrap>", line 241, in _call_with_frames_removed
  File "/data2/repos/humble/humble/launch_ros/launch_ros/launch_ros/__init__.py", line 17, in <module>
    from . import actions
  File "/data2/repos/humble/humble/launch_ros/launch_ros/launch_ros/actions/__init__.py", line 17, in <module>
    from .composable_node_container import ComposableNodeContainer
  File "/data2/repos/humble/humble/launch_ros/launch_ros/launch_ros/actions/composable_node_container.py", line 27, in <module>
    from .node import Node
  File "/data2/repos/humble/humble/launch_ros/launch_ros/launch_ros/actions/node.py", line 48, in <module>
    from launch_ros.parameters_type import SomeParameters
  File "/data2/repos/humble/humble/launch_ros/launch_ros/launch_ros/parameters_type.py", line 50, in <module>
    SomeSubstitutionsType_types_tuple +
TypeError: unsupported operand type(s) for +: 'SomeSubstitutionsType_types_tuple' and 'tuple'

[RMichaelSwan]

Is there any way to generate the XML / YAML documentation also? I find myself having to look at the launch_ros python code just to find what entities are available in XML launch files.

[rkent]

Where are those files? I don't see any XML or YAML files in launch_ros

[RMichaelSwan]

Where are those files? I don't see any XML or YAML files in launch_ros

I am referring to the XML / YAML ros2 launch formats defined through launch: https://github.com/ros2/launch. One example I could give is that SetParameter can be included in XML as

<launch>
  <set_parameter name="use_sim_time" value="true"/>
  ...
</launch>

But this is not documented anywhere. You have to search launch_ros for @expose and figure out how to use it. It would be nice if something like this document were automated.

[rkent]

I'm afraid that my beat is to get rosdoc2 to work properly with packages, that is it should show whatever documentation the package author has prepared. If there is no documentation available, then rosdoc2 cannot solve that. I've actually never run ros2 launch_ros myself, so I am not the person to add missing documentation.

[christophebedard]

I am referring to the XML / YAML ros2 launch formats defined through launch: https://github.com/ros2/launch

It's a different issue. For XML/YAML launch frontend documentation, see #404. I have a WIP PR: #409.