Allow rustdoc to run without a ROS distribution

[esteve]

Fixes #336

[esteve]

@Carter12s can you have a look at this? Thanks.

I believe this should work with docs.rs, if you pass the feature flag generate_docs (i.e. cargo rustdoc --features generate_docs), it'll generate documentation without requiring a ROS distribution, so in theory it'd work with docs.rs.

[Carter12s]

Hey @esteve awesome that you're taking a stab at this. I did make a half hearted attempt a few weeks back, but didn't see any good way to make progress. Your solution is way cleaner than what I was attempting. However, when I went to test this I found you didn't quite make enough changes for it actually work, I pushed what I believe is a working solution to: https://github.com/Carter12s/ros2_rust/tree/docs.rs

It appears that when running cargo doc even thou it doesn't invoke build.rs for the main package it does invoke build.rs for dependencies, this means that the build.rs for rosidl_runtime_rs gets invoked and fails due to AMENT_PACKAGE_PATH being missing. Adding (and passing through) a generate_docs feature to that crate resolved the issue for me.

I actually published successful versions to some alias on docs.rs so you can see a working version with my changes here:
https://docs.rs/do-not-use-testing-rclrs/0.4.1/do_not_use_testing_rclrs/
and here: https://docs.rs/do-not-use-testing-rosidl_runtime_rs/0.4.0/do_not_use_testing_rosidl_runtime_rs/

[esteve]

@Carter12s that's fantastic, thanks! I did run cargo rustdoc in the folder that has rclrs, I don't know why it didn't complain about rosidl_runtime_rs. Anyway, your changes look great, I'll merge them into this branch, I can publish a small update (0.4.1) so that we show up on docs.rs Thanks!

[esteve]

@Carter12s I've added your changes and a check to make sure that build.rs fails if ROS_DISTRO is not set and generate_docs is not enabled. Could you have a look when you have a moment? Thanks.

[Carter12s]

Changes look good to me. No idea what the right way to make clippy not angry is...

[esteve]

@Carter12s yeah, we either add all of rcl_bindings_generated.rs to the tree or just skip clippy from running for the generate_docs flag. Any suggestions? I'm leaning towards the latter.

[Carter12s]

Yeah skipping it makes sense to me.

[esteve]

@Carter12s yay! I managed to make it all build without warnings or errors. Could you have another look? Thanks.

[jhdcs]

This looks good to me, though I'm wondering if we should find a spot to document our policies and procedures, as well as other things that developers don't often bump into. For instance, what the steps are for releasing a new version, or how getting rustdoc to run without a ROS distribution is supposed to work. I can foresee a potential maintenance issue in future where the knowledge gets lost/forgotten when we need it.

I don't think it's needed for this particular PR, though. Just food for future thought.

[jhdcs]

Should we document somewhere about how this feature works?

[esteve]

@jhdcs good point. Where do you think it'd be the best place for this?

[jhdcs]

I'm not sure, it depends on how much information needs to be conveyed. If it can be summarized in a couple of sentences, you might be able to get away with doing it in the comments here. Otherwise, we may need to create a separate documentation file...

[esteve]

This feature's only purpose is so that docs.rs can run ros2-rust, so it's not intended to be used by users.

[esteve]

But nevertheless, I agree with documenting it somewhere, I'll add something more explanatory here and we can move it elsewhere if it needs more details.

[esteve]

@jhdcs can you approve this PR again if it looks good to you? I pushed a change and your review was unfortunately discarded. Thanks.