advanced_logging example

[avanmalleghem]

Related to issue #431
I saw that someone is already working on a simple example (#459) so I worked on a more complex example to show the capabilities of the logging system.

If I may add something, it is quite difficult to find documentation about logging capabilities in ROS Rust. Is there a way I can help to improve it ? or maybe I just checked the wrong place.

(I tested it on Jazzy)

[romainreignier]

As a new user of ros2_rust, I agree that an example like this is useful, but I have then built the doc of rclrs with cargo doc and from the first page:

we have a link to the log page:

In which we have more or less the same content as your example.

So instead of adding basic examples, maybe the step forward it to publish the rclrs doc somewhere and advertise it at the start of the README?

[esteve]

@romainreignier we publish our generated documentation on https://docs.rs/rclrs/latest/rclrs/ and https://docs.rs/rosidl_runtime_rs/latest/rosidl_runtime_rs/, but it's true we should add a link to both, I'll do that later today.

[romainreignier]

Ok, thanks, but this documentation is outdated, there is no logging in it.
Because ros2_rust is quite WIP, maybe adding a Github workflow to publish the doc of the main branch to Github pages and point it in the README could be more useful.
I am trying to get a workflow running here: https://github.com/romainreignier/ros2_rust/blob/feature/add_doc_job/.github/workflows/docs.yml

[Guelakais]

Why not advance the workflow to publish to https://docs.rs/? github pages would be an extra target to worry about.

Ok, thanks, but this documentation is outdated, there is no logging in it. Because ros2_rust is quite WIP, maybe adding a Github workflow to publish the doc of the main branch to Github pages and point it in the README could be more useful. I am trying to get a workflow running here: https://github.com/romainreignier/ros2_rust/blob/feature/add_doc_job/.github/workflows/docs.yml

[romainreignier]

Sure, but I have no idea what is the release plan for the project so in the meantime, I though that Github Pages might be an option.

[romainreignier]

I am trying to get a workflow running here: https://github.com/romainreignier/ros2_rust/blob/feature/add_doc_job/.github/workflows/docs.yml

I had some issues but this is now resolved and the doc is available here: https://romainreignier.github.io/ros2_rust/rclrs/index.html
I will do a PR and see what the maintainers think about it.

[esteve]

Why not advance the workflow to publish to https://docs.rs/? github pages would be an extra target to worry about.

Because docs.rs only generates documentation for published crates, logging is part of the current main branch and we're waiting to finish some changes before making a new release.

[Guelakais]

I understand. So having proper documentation is of course important. On the other hand, rclrs has many examples from which you can easily deduce how it works. I think as long as the current documentation of rclrs does not contradict the current state of development, it should be ok. Otherwise, measures should be taken to make this visible.

[esteve]

I think as long as the current documentation of rclrs does not contradict the current state of development, it should be ok.

The current documentation on docs.rs matches the latest released version of the rclrs crate.

Otherwise, measures should be taken to make this visible

What kind of measures do you propose?

[Guelakais]

I think as long as the current documentation of rclrs does not contradict the current state of development, it should be ok.

The current documentation on docs.rs matches the latest released version of the rclrs crate.

Otherwise, measures should be taken to make this visible

What kind of measures do you propose?

Difficult question. At present, the README.md already contains instructions on how to install ros2_rust. If in doubt, you could also add a disclaimer there to point out that the current documentation on docs.rs is out of date.

[esteve]

If in doubt, you could also add a disclaimer there to point out that the current documentation on docs.rs is out of date.

It is not out of date, the documentation on docs.rs documents the latest released version of rclrs. If you want to build rclrs from main, the documentation can still be generated via cargo doc. This is the same for every Rust crate out there, it's not specific to rclrs, unless you mean that every other crate on docs.rs is also out of date compared to their main branch.

[Guelakais]

We had already clarified that. As already discussed, the situation should be ok for the time being. There are certainly examples where the documentation is misleading, as I had already established. At the same time, the compiler toolchain of ros2 is more the problem than the current documentation.