search

ros2 / launch_ros

Tools for launching ROS nodes and for writing tests involving ROS nodes.
Apache License 2.0
59 stars 72 forks source link

Published API documentation #232

Open adamsj-ros opened 3 years ago

adamsj-ros commented 3 years ago

Bug report

Required Info:

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 commented 3 years ago

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 commented 3 years ago

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 commented 2 years ago

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 commented 2 years ago

+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 commented 2 years ago

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 git@github.com: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:

image