Allow rustdoc to run without a ROS distribution (#347)

* Allow rustdoc to run without a ROS distribution

* Extensions to get working

* Fail if generate_docs feature is not enabled and ROS_DISTRO is not set

* Fix formatting

* Fix formatting

* Make clippy slightly less unhappy

* Do not run clippy for all features if checking rclrs

* Clean up rcl_bindings.rs

* Fix comparison

* Avoid warnings for rosidl_runtime_rs

* Avoid running cargo test with all features for rclrs

* Ignore rosidl_runtime_rs for cargo test

* rosidl_runtime_rs does not have a dyn_msg feature

* Add comment about the generate_docs feature

---------

Co-authored-by: carter <[email protected]>

Author: esteve

rosidl_runtime_rs/Cargo.toml

@@ -17,8 +17,21 @@ path = "src/lib.rs"
 # formats such as JSON, YAML, Pickle, etc.
 serde = { version = "1", optional = true }
 
+[features]
+default = []
+# This feature is solely for the purpose of being able to generate documetation without a ROS installation
+# The only intended usage of this feature is for docs.rs builders to work, and is not intended to be used by end users
+generate_docs = []
+
 [dev-dependencies]
 # Needed for writing property tests
 quickcheck = "1"
 # Needed for testing serde support
 serde_json = "1"
+
+[build-dependencies]
+# Needed for uploading documentation to docs.rs
+cfg-if = "1.0.0"
+
+[package.metadata.docs.rs]
+features = ["generate_docs"]

rosidl_runtime_rs/build.rs

@@ -1,24 +1,31 @@
-use std::env;
-use std::path::Path;
+cfg_if::cfg_if! {
+    if #[cfg(not(feature="generate_docs"))] {
+        use std::env;
+        use std::path::Path;
 
-const AMENT_PREFIX_PATH: &str = "AMENT_PREFIX_PATH";
+        const AMENT_PREFIX_PATH: &str = "AMENT_PREFIX_PATH";
 
-fn get_env_var_or_abort(env_var: &'static str) -> String {
-    if let Ok(value) = env::var(env_var) {
-        value
-    } else {
-        panic!(
-            "{} environment variable not set - please source ROS 2 installation first.",
-            env_var
-        );
+        fn get_env_var_or_abort(env_var: &'static str) -> String {
+            if let Ok(value) = env::var(env_var) {
+                value
+            } else {
+                panic!(
+                    "{} environment variable not set - please source ROS 2 installation first.",
+                    env_var
+                );
+            }
+        }
     }
 }
 
 fn main() {
-    let ament_prefix_path_list = get_env_var_or_abort(AMENT_PREFIX_PATH);
-    for ament_prefix_path in ament_prefix_path_list.split(':') {
-        let library_path = Path::new(ament_prefix_path).join("lib");
-        println!("cargo:rustc-link-search=native={}", library_path.display());
+    #[cfg(not(feature = "generate_docs"))]
+    {
+        let ament_prefix_path_list = get_env_var_or_abort(AMENT_PREFIX_PATH);
+        for ament_prefix_path in ament_prefix_path_list.split(':') {
+            let library_path = Path::new(ament_prefix_path).join("lib");
+            println!("cargo:rustc-link-search=native={}", library_path.display());
+        }
     }
 
     // Invalidate the built crate whenever this script changes