Add the `docsrs` autocfg attr to all crates (#3295)

CHANGELOG.next.toml

@@ -80,6 +80,18 @@ references = ["aws-sdk-rust#990"]
 meta = { "breaking" = false, "tada" = false, "bug" = false, "target" = "client" }
 author = "declanvk"
 
+[[smithy-rs]]
+message = "All generated docs now include docsrs labels when features are required"
+references = ["smithy-rs#3121", "smithy-rs#3295"]
+meta = { "breaking" = false, "tada" = true, "bug" = false, "target" = "all" }
+author = "rcoh"
+
+[[aws-sdk-rust]]
+message = "All generated docs now include docsrs labels when features are required"
+references = ["smithy-rs#3121", "smithy-rs#3295"]
+meta = { "breaking" = false, "tada" = true, "bug" = false }
+author = "rcoh"
+
 [[smithy-rs]]
 message = "[`Number`](https://docs.rs/aws-smithy-types/latest/aws_smithy_types/enum.Number.html) `TryInto` implementations now succesfully convert from `f64` to numeric types when no precision is lost. This fixes some deserialization issues where numbers like `25.0` were sent when `Byte` fields were expected."
 references = ["smithy-rs#3294"]

aws/rust-runtime/aws-config/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![allow(clippy::derive_partial_eq_without_eq)]
 #![warn(
     missing_debug_implementations,
@@ -11,7 +14,6 @@
     rustdoc::missing_crate_level_docs,
     unreachable_pub
 )]
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 //! `aws-config` provides implementations of region and credential resolution.
 //!

aws/rust-runtime/aws-credential-types/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! `aws-credential-types` provides types concerned with AWS SDK credentials including:
 //! * Traits for credentials providers and for credentials caching
 //! * An opaque struct representing credentials

aws/rust-runtime/aws-endpoint/src/lib.rs

@@ -3,4 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! This crate is no longer used by the AWS SDK and is deprecated.

aws/rust-runtime/aws-http/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! AWS-specific middleware implementations and HTTP-related features.
 
 #![allow(clippy::derive_partial_eq_without_eq)]

aws/rust-runtime/aws-hyper/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![deprecated(
     since = "0.3.0",
     note = "The functionality of this crate is included in individual AWS services."

aws/rust-runtime/aws-inlineable/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! Collection of modules that get conditionally included directly into the code generated
 //! SDK service crates. For example, when generating S3, the `s3_errors` module will get copied
 //! into the generated S3 crate to support the code generator.

aws/rust-runtime/aws-runtime-api/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! Runtime support code for the AWS SDK. This crate isn't intended to be used directly.
 
 #![warn(

aws/rust-runtime/aws-runtime/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! Runtime support code for the AWS SDK. This crate isn't intended to be used directly.
 
 #![warn(

aws/rust-runtime/aws-sig-auth/src/lib.rs

@@ -3,4 +3,7 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! This crate is no longer used by the AWS SDK and is deprecated.

aws/rust-runtime/aws-sigv4/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! Provides functions for calculating Sigv4 signing keys, signatures, and
 //! optional utilities for signing HTTP requests and Event Stream messages.
 

aws/rust-runtime/aws-types/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! Cross-service types for the AWS SDK.
 
 #![allow(clippy::derive_partial_eq_without_eq)]

codegen-core/src/main/kotlin/software/amazon/smithy/rust/codegen/core/smithy/generators/LibRsGenerator.kt

@@ -12,6 +12,7 @@ import software.amazon.smithy.rust.codegen.core.rustlang.Writable
 import software.amazon.smithy.rust.codegen.core.rustlang.containerDocs
 import software.amazon.smithy.rust.codegen.core.rustlang.escape
 import software.amazon.smithy.rust.codegen.core.rustlang.isNotEmpty
+import software.amazon.smithy.rust.codegen.core.rustlang.rawRust
 import software.amazon.smithy.rust.codegen.core.rustlang.rust
 import software.amazon.smithy.rust.codegen.core.smithy.CoreRustSettings
 import software.amazon.smithy.rust.codegen.core.smithy.customize.NamedCustomization
@@ -50,6 +51,7 @@ class LibRsGenerator(
             if (requireDocs) {
                 rust("##![warn(missing_docs)]")
             }
+            rawRust("#![cfg_attr(docsrs, feature(doc_auto_cfg))]")
 
             // Allow for overriding the default service docs via customization
             val defaultServiceDocs = settings.getService(model).getTrait<DocumentationTrait>()?.value

rust-runtime/aws-smithy-async/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![allow(clippy::derive_partial_eq_without_eq)]
 #![warn(
     missing_docs,

rust-runtime/aws-smithy-checksums/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![allow(clippy::derive_partial_eq_without_eq)]
 #![warn(
     // missing_docs,

rust-runtime/aws-smithy-client/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! This crate is no longer used by smithy-rs and is deprecated.
 
 #![warn(

rust-runtime/aws-smithy-eventstream/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![allow(clippy::derive_partial_eq_without_eq)]
 #![warn(
     // missing_docs,

rust-runtime/aws-smithy-http-auth/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![warn(
     missing_docs,
     rustdoc::missing_crate_level_docs,

rust-runtime/aws-smithy-http-server-python/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![allow(clippy::derive_partial_eq_without_eq)]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 

rust-runtime/aws-smithy-http-server-typescript/src/lib.rs

@@ -2,3 +2,7 @@
  * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
  * SPDX-License-Identifier: Apache-2.0
  */
+
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */

rust-runtime/aws-smithy-http-server/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![allow(clippy::derive_partial_eq_without_eq)]
 #![cfg_attr(docsrs, feature(doc_cfg))]
 

rust-runtime/aws-smithy-http-tower/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! This crate is no longer used by smithy-rs and is deprecated.
 
 #![warn(

rust-runtime/aws-smithy-http/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![warn(
     missing_docs,
     rustdoc::missing_crate_level_docs,

rust-runtime/aws-smithy-json/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![allow(clippy::derive_partial_eq_without_eq)]
 #![warn(
     // missing_docs,

rust-runtime/aws-smithy-protocol-test/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![warn(
     // missing_docs,
     // rustdoc::missing_crate_level_docs,

rust-runtime/aws-smithy-query/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![allow(clippy::derive_partial_eq_without_eq)]
 #![warn(
     // missing_docs,

rust-runtime/aws-smithy-runtime-api/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![warn(
     missing_docs,
     rustdoc::missing_crate_level_docs,

rust-runtime/aws-smithy-runtime/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! Runtime support logic and types for smithy-rs generated code.
 //!
 //! # Crate Features
@@ -17,7 +20,6 @@
     unreachable_pub,
     rust_2018_idioms
 )]
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
 
 /// Runtime support logic for generated clients.
 #[cfg(feature = "client")]

rust-runtime/aws-smithy-types-convert/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! Conversions between `aws-smithy-types` and the types of frequently used Rust libraries.
 
 #![allow(clippy::derive_partial_eq_without_eq)]

rust-runtime/aws-smithy-types/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 //! Protocol-agnostic types for smithy-rs.
 
 #![allow(clippy::derive_partial_eq_without_eq)]
@@ -13,7 +16,7 @@
     rust_2018_idioms,
     unreachable_pub
 )]
-#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+
 pub mod base64;
 pub mod body;
 pub mod byte_stream;

rust-runtime/aws-smithy-xml/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #![allow(clippy::derive_partial_eq_without_eq)]
 #![warn(
     // missing_docs,

rust-runtime/inlineable/src/lib.rs

@@ -3,6 +3,9 @@
  * SPDX-License-Identifier: Apache-2.0
  */
 
+/* Automatically managed default lints */
+#![cfg_attr(docsrs, feature(doc_auto_cfg))]
+/* End of automatically managed default lints */
 #[allow(dead_code)]
 mod aws_query_compatible_errors;
 #[allow(unused)]

tools/ci-build/sdk-lints/src/anchor.rs

@@ -19,6 +19,7 @@ pub fn replace_anchor(
     haystack: &mut String,
     anchors: &(impl AsRef<str>, impl AsRef<str>),
     new_content: &str,
+    default_insertion_position: Option<usize>,
 ) -> anyhow::Result<bool> {
     let anchor_start = anchors.0.as_ref();
     let anchor_end = anchors.1.as_ref();
@@ -27,10 +28,19 @@ pub fn replace_anchor(
         if haystack.contains(anchor_end) {
             bail!("found end anchor but no start anchor");
         }
-        haystack.push('\n');
-        haystack.push_str(anchor_start);
-        haystack.push_str(new_content);
-        haystack.push_str(anchor_end);
+
+        let (prefix, suffix) = match default_insertion_position {
+            Some(position) => haystack.split_at(position),
+            None => (haystack.as_ref(), ""),
+        };
+        let mut out = String::new();
+        out.push_str(prefix);
+        out.push('\n');
+        out.push_str(anchor_start);
+        out.push_str(new_content);
+        out.push_str(anchor_end);
+        out.push_str(suffix);
+        *haystack = out;
         return Ok(true);
     }
     let start = start.unwrap_or_else(|| haystack.find(anchor_start).expect("must be present"));
@@ -59,7 +69,7 @@ mod test {
     #[test]
     fn updates_empty() {
         let mut text = "this is the start".to_string();
-        assert!(replace_anchor(&mut text, &anchors("foo"), "hello!").unwrap());
+        assert!(replace_anchor(&mut text, &anchors("foo"), "hello!", None).unwrap());
         assert_eq!(
             text,
             "this is the start\n<!-- anchor_start:foo -->hello!<!-- anchor_end:foo -->"
@@ -70,13 +80,13 @@ mod test {
     fn updates_existing() {
         let mut text =
             "this is the start\n<!-- anchor_start:foo -->hello!<!-- anchor_end:foo -->".to_string();
-        assert!(replace_anchor(&mut text, &anchors("foo"), "goodbye!").unwrap());
+        assert!(replace_anchor(&mut text, &anchors("foo"), "goodbye!", None).unwrap());
         assert_eq!(
             text,
             "this is the start\n<!-- anchor_start:foo -->goodbye!<!-- anchor_end:foo -->"
         );
 
         // no replacement should return false
-        assert!(!replace_anchor(&mut text, &anchors("foo"), "goodbye!").unwrap(),)
+        assert!(!replace_anchor(&mut text, &anchors("foo"), "goodbye!", None).unwrap(),)
     }
 }

tools/ci-build/sdk-lints/src/lib_rs_attr.rs

@@ -0,0 +1,60 @@
+/*
+ * Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+ * SPDX-License-Identifier: Apache-2.0
+ */
+
+use std::path::{Path, PathBuf};
+
+use crate::all_runtime_crates;
+use crate::anchor::replace_anchor;
+use crate::lint::{Fix, Lint, LintError};
+
+/// Manages a standard set of `#![crate_level]` attributes
+pub(super) struct StandardizedRuntimeCrateLibRsAttributes;
+
+impl Lint for StandardizedRuntimeCrateLibRsAttributes {
+    fn name(&self) -> &str {
+        "Checking for the correct docs.rs attributes"
+    }
+
+    fn files_to_check(&self) -> anyhow::Result<Vec<PathBuf>> {
+        Ok(all_runtime_crates()?
+            .map(|crte| crte.join("src/lib.rs"))
+            .collect())
+    }
+}
+
+const DOCS_AUTO_CFG: &str = "#![cfg_attr(docsrs, feature(doc_auto_cfg))]";
+
+fn check_for_auto_cfg(path: impl AsRef<Path>) -> anyhow::Result<Vec<LintError>> {
+    let contents = std::fs::read_to_string(path)?;
+    if !contents.contains(DOCS_AUTO_CFG) {
+        return Ok(vec![LintError::new("missing docsrs header")]);
+    }
+    Ok(vec![])
+}
+
+impl Fix for StandardizedRuntimeCrateLibRsAttributes {
+    fn fix(&self, path: impl AsRef<Path>) -> anyhow::Result<(Vec<LintError>, String)> {
+        let contents = std::fs::read_to_string(&path)?;
+        // ensure there is only one in the crate
+        let mut contents = contents.replace(DOCS_AUTO_CFG, "");
+        let anchor_start = "/* Automatically managed default lints */\n";
+        let anchor_end = "\n/* End of automatically managed default lints */";
+        // Find the end of the license header
+        if let Some(pos) = contents.find("*/") {
+            let newline = contents[pos..]
+                .find('\n')
+                .ok_or(anyhow::Error::msg("couldn't find a newline"))?
+                + 1
+                + pos;
+            replace_anchor(
+                &mut contents,
+                &(anchor_start, anchor_end),
+                DOCS_AUTO_CFG,
+                Some(newline),
+            )?;
+        };
+        check_for_auto_cfg(path).map(|errs| (errs, contents))
+    }
+}

tools/ci-build/sdk-lints/src/lint_cargo_toml.rs

@@ -224,6 +224,7 @@ fn fix_docs_rs(contents: &str) -> Result<String> {
         &mut new,
         &("[package.metadata.docs.rs]", "# End of docs.rs metadata"),
         DEFAULT_DOCS_RS_SECTION,
+        None,
     )?;
     Ok(new)
 }

tools/ci-build/sdk-lints/src/main.rs

@@ -5,6 +5,7 @@
 
 use crate::changelog::ChangelogNext;
 use crate::copyright::CopyrightHeader;
+use crate::lib_rs_attr::StandardizedRuntimeCrateLibRsAttributes;
 use crate::lint::{Check, Fix, Lint, LintError, Mode};
 use crate::lint_cargo_toml::{
     CrateAuthor, CrateLicense, DocsRs, SdkExternalLintsExposesStableCrates,
@@ -23,6 +24,7 @@ use std::{fs, io};
 mod anchor;
 mod changelog;
 mod copyright;
+mod lib_rs_attr;
 mod lint;
 mod lint_cargo_toml;
 mod readmes;
@@ -140,6 +142,7 @@ fn main() -> Result<()> {
             }
             errs.extend(StableCratesExposeStableCrates::new()?.check_all()?);
             errs.extend(SdkExternalLintsExposesStableCrates::new()?.check_all()?);
+            errs.extend(StandardizedRuntimeCrateLibRsAttributes.check_all()?);
             ok(errs)?
         }
         Args::Fix {
@@ -158,6 +161,7 @@ fn main() -> Result<()> {
             if docsrs_metadata || all {
                 ok(DocsRs.fix_all(dry_run)?)?;
             }
+            ok(StandardizedRuntimeCrateLibRsAttributes.fix_all(dry_run)?)?;
         }
     }
     Ok(())

tools/ci-build/sdk-lints/src/readmes.rs

@@ -78,7 +78,11 @@ fn fix_readme(path: impl AsRef<Path>, to_be_used_directly: bool) -> Result<(bool
 
     let mut contents = fs::read_to_string(path.as_ref())
         .with_context(|| format!("failure to read readme: {:?}", path.as_ref()))?;
-    let updated =
-        anchor::replace_anchor(&mut contents, &anchor::anchors("footer"), &footer_contents)?;
+    let updated = anchor::replace_anchor(
+        &mut contents,
+        &anchor::anchors("footer"),
+        &footer_contents,
+        None,
+    )?;
     Ok((updated, contents))
 }