Best approaches to support docsrs mode in user code

[nyurik]

My crate needs to generate the docs.rs documentation despite the fairly involved compilation with the native bindings, which cannot easily happen inside the docsrs docker constraints.

If my cxx bridge includes some header files and types, would it be possible to somehow generate special shims for the native stuff, possibly with a custom attribute, to let cxx simplify the docsrs generation?

#[cxx::bridge(namespace = "mln::bridge")]
pub mod ffi {
    // This should be part of the docs
    #[repr(u32)]
    #[derive(Debug, Clone, Copy, PartialEq, Eq)]
    enum MapMode {
        Continuous,
        Static,
        Tile,
    }

    unsafe extern "C++" {
        // include! requires git clone of a large library, downloads, etc,
        // and should be avoided in docsrs
        #[cfg(not(docsrs))]  // <-- this should skip including external file, while passing all the other parts
        include!("map_renderer.h");

        // This is an error in docsrs because the type is defined in the header file
        // It needs some fake shim instead
        type MapRenderer;

        fn MapRenderer_new(mapMode: MapMode) -> UniquePtr<MapRenderer>;
    }
}