Have a "docs-only" feature that should be enabled when building the doc

The build may fail while building the docs because the necessary
C++ dependencies might be missing.
So just ignore the failling build when building the documentation

For example: woboq/qmetaobject-rs#27

Author: ogoffart

cpp_build/Cargo.toml

@@ -18,3 +18,6 @@ syn = { version = "0.15", features=["full", "visit"] }
 proc-macro2 = "0.4"
 regex = "1"
 unicode-xid = "0.1"
+
+[package.metadata.docs.rs]
+features = [ "docs-only" ]

cpp_build/src/lib.rs

@@ -644,7 +644,11 @@ In order to provide a better error message, the build script will exit successfu
             self.cc.flag_if_supported("-std=c++11");
         }
         // Build the C++ library
-        self.cc.file(filename).compile(LIB_NAME);
+        if let Err(e) = self.cc.file(filename).try_compile(LIB_NAME) {
+            let _ = writeln!(std::io::stderr(), "\n\nerror occurred: {:?}\n\n", e);
+            #[cfg(not(feature = "docs-only"))]
+            std::process::exit(1);
+        }
     }
 }
 

cpp_macros/Cargo.toml

@@ -21,3 +21,6 @@ quote = "0.6"
 proc-macro2 = "0.4"
 aho-corasick = "0.6"
 byteorder = "1.0"
+
+[package.metadata.docs.rs]
+features = [ "docs-only" ]

cpp_macros/src/lib.rs

@@ -48,13 +48,25 @@ impl MetaData {
 
 lazy_static! {
     static ref METADATA: HashMap<u64, Vec<MetaData>> = {
-        let file = open_lib_file().expect(
+        let file = match open_lib_file() {
+            Ok(x) => x,
+            Err(e) => {
+                #[cfg(not(feature = "docs-only"))]
+                panic!(
             r#"
 -- rust-cpp fatal error --
 
 Failed to open the target library file.
-NOTE: Did you make sure to add the rust-cpp build script?"#,
-        );
+NOTE: Did you make sure to add the rust-cpp build script?
+{}"#,
+                e);
+                #[cfg(feature = "docs-only")]
+                {
+                    eprintln!("Error while opening target library: {}", e);
+                    return Default::default()
+                };
+            }
+        };
 
         read_metadata(file).expect(
             r#"
@@ -191,10 +203,19 @@ pub fn expand_internal(input: proc_macro::TokenStream) -> proc_macro::TokenStrea
     let size_data = match METADATA.get(&closure.sig.name_hash()) {
         Some(x) => x,
         None => {
+            #[cfg(not(feature = "docs-only"))]
             return quote!(compile_error!{
 r#"This cpp! macro is not found in the library's rust-cpp metadata.
 NOTE: Only cpp! macros found directly in the program source will be parsed -
-NOTE: They cannot be generated by macro expansion."#}).into()
+NOTE: They cannot be generated by macro expansion."#}).into();
+            #[cfg(feature = "docs-only")]
+            {
+                return quote!{
+                    macro_rules! __cpp_closure_impl {
+                        ($($x:tt)*) => { panic!("docs-only"); }
+                    }
+                }.into()
+            };
         }
     };
 
@@ -362,15 +383,60 @@ pub fn expand_wrap_class(input: proc_macro::TokenStream) -> proc_macro::TokenStr
     };
 
     let hash = class.name_hash();
+    let class_name = class.name.clone();
 
     // Get the size data compiled by the build macro
     let size_data = match METADATA.get(&hash) {
         Some(x) => x,
         None => {
+            #[cfg(not(feature = "docs-only"))]
             return quote!(compile_error!{
 r#"This cpp_class! macro is not found in the library's rust-cpp metadata.
 NOTE: Only cpp_class! macros found directly in the program source will be parsed -
-NOTE: They cannot be generated by macro expansion."#}).into()
+NOTE: They cannot be generated by macro expansion."#}).into();
+            #[cfg(feature = "docs-only")]
+            {
+                let mut result = quote!{
+                    #[doc(hidden)]
+                    impl ::cpp::CppTrait for #class_name {
+                        type BaseType = usize;
+                        const ARRAY_SIZE: usize = 1;
+                        const CPP_TYPE: &'static str = stringify!(#class_name);
+                    }
+                    #[doc = "NOTE: this trait will only be enabled if the C++ underlying type is trivially copyable"]
+                    impl ::std::marker::Copy for #class_name { }
+                    #[doc = "NOTE: this trait will only be enabled if the C++ underlying type is copyable"]
+                    impl ::std::clone::Clone for #class_name {  fn clone(&self) -> Self { panic!("docs-only") } }
+                    #[doc = "NOTE: this trait will only be enabled if the C++ underlying type is default constructible"]
+                    impl ::std::default::Default for #class_name { fn default() -> Self { panic!("docs-only") } }
+                };
+                if class.derives("PartialEq") {
+                    result = quote!{ #result
+                        impl ::std::cmp::PartialEq for #class_name {
+                            fn eq(&self, other: &#class_name) -> bool { panic!("docs-only") }
+                        }
+                    };
+                }
+                if class.derives("PartialOrd") {
+                    result = quote!{ #result
+                        impl ::std::cmp::PartialOrd for #class_name {
+                            fn partial_cmp(&self, other: &#class_name) -> ::std::option::Option<::std::cmp::Ordering> {
+                                panic!("docs-only")
+                            }
+                        }
+                    };
+                }
+                if class.derives("Ord") {
+                    result = quote!{ #result
+                        impl ::std::cmp::Ord for #class_name {
+                            fn cmp(&self, other: &#class_name) -> ::std::cmp::Ordering {
+                                panic!("docs-only")
+                            }
+                        }
+                    };
+                }
+                return result.into()
+            };
         }
     };
 
@@ -387,7 +453,6 @@ NOTE: They cannot be generated by macro expansion."#}).into()
     let destructor_name = Ident::new(&format!("__cpp_destructor_{}", hash), Span::call_site());
     let copyctr_name = Ident::new(&format!("__cpp_copy_{}", hash), Span::call_site());
     let defaultctr_name = Ident::new(&format!("__cpp_default_{}", hash), Span::call_site());
-    let class_name = class.name.clone();
 
     let mut result = quote! {
         #[doc(hidden)]