Add external docs url config option

src/codegen/general.rs

@@ -129,6 +129,13 @@ pub fn define_fundamental_type(
     let sys_crate_name = env.main_sys_crate_name();
     writeln!(w, "{} {{", use_glib_type(env, "wrapper!"))?;
     doc_alias(w, glib_name, "", 1)?;
+    external_doc_link(
+        w,
+        env.config.external_docs_url.as_deref(),
+        type_name,
+        &visibility,
+        1,
+    )?;
     writeln!(
         w,
         "\t{} struct {}(Shared<{}::{}>);",
@@ -235,6 +242,13 @@ pub fn define_object_type(
 
     writeln!(w, "{} {{", use_glib_type(env, "wrapper!"))?;
     doc_alias(w, glib_name, "", 1)?;
+    external_doc_link(
+        w,
+        env.config.external_docs_url.as_deref(),
+        type_name,
+        &visibility,
+        1,
+    )?;
     if parents.is_empty() {
         writeln!(
             w,
@@ -909,6 +923,29 @@ pub fn doc_alias(w: &mut dyn Write, name: &str, comment_prefix: &str, indent: us
     )
 }
 
+pub fn external_doc_link(
+    w: &mut dyn Write,
+    external_url: Option<&str>,
+    name: &str,
+    visibility: &Visibility,
+    indent: usize,
+) -> Result<()> {
+    // Don't generate the external doc link on non-public types.
+    if !visibility.is_public() {
+        Ok(())
+    } else if let Some(external_url) = external_url {
+        writeln!(
+            w,
+            "{}/// This documentation is incomplete due to license restrictions and limitations on docs.rs. Please have a look at [our official docs]({}/index.html?search={}) for more information.",
+            tabs(indent),
+            external_url.trim_end_matches('/'),
+            name
+        )
+    } else {
+        Ok(())
+    }
+}
+
 pub fn doc_hidden(
     w: &mut dyn Write,
     doc_hidden: bool,

src/config/config.rs

@@ -118,6 +118,10 @@ pub struct Config {
     pub extra_versions: Vec<Version>,
     pub lib_version_overrides: HashMap<Version, Version>,
     pub feature_dependencies: HashMap<Version, Vec<String>>,
+    /// An url that will be inserted into the docs as link that links
+    /// to another doc source, for example when builds on docs.rs
+    /// are limited due to license issues.
+    pub external_docs_url: Option<String>,
 }
 
 impl Config {
@@ -344,6 +348,7 @@ impl Config {
         let extra_versions = read_extra_versions(&toml)?;
         let lib_version_overrides = read_lib_version_overrides(&toml)?;
         let feature_dependencies = read_feature_dependencies(&toml)?;
+        let external_docs_url = read_external_docs_url(&toml)?;
 
         Ok(Config {
             work_mode,
@@ -372,6 +377,7 @@ impl Config {
             extra_versions,
             lib_version_overrides,
             feature_dependencies,
+            external_docs_url,
         })
     }
 
@@ -527,6 +533,17 @@ fn read_feature_dependencies(toml: &toml::Value) -> Result<HashMap<Version, Vec<
     Ok(map)
 }
 
+fn read_external_docs_url(toml: &toml::Value) -> Result<Option<String>, String> {
+    Ok(
+        if let Some(value) = toml.lookup("options.external_docs_url") {
+            let value = value.as_result_str("options.external_docs_url")?;
+            Some(value.to_string())
+        } else {
+            None
+        },
+    )
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;