fix: Generate smithy runtime module docs & include in index page (#1665)

* Update doc generation CLI command to include AWS runtime modules.

* Ignore .DS_Store file when getting AWS runtime modules.

* Extra spacing between header and following lists.

* Add Smithy runtime modules to be included in doc index page. Also, modify GitHub workflow to generate docs for smithy-swift modules and upload to S3 bucket as well.

* Resolve PR comments

---------

Co-authored-by: Sichan Yoo <chanyoo@amazon.com>

.github/workflows/generate-documentation.yml

@@ -22,8 +22,15 @@ jobs:
     outputs:
       version: ${{ steps.set-version.outputs.version }}
     steps:
-      - name: Checkout Sources
+      - name: Checkout aws-sdk-swift
         uses: actions/checkout@v4
+      - name: Checkout smithy-swift
+        uses: actions/checkout@v4
+        with:
+          repository: smithy-lang/smithy-swift
+          path: smithy-swift
+      - name: Move smithy-swift into place
+        run: mv smithy-swift ..
       - name: Configure AWS Credentials
         uses: aws-actions/configure-aws-credentials@v4
         with:
@@ -50,10 +57,15 @@ jobs:
             echo "Error: runs on a tag only"
             exit 1
           fi
-      - name: Generate docs
+      - name: Generate aws-sdk-swift docs
         run: |
           DOCS_BUCKET=${{ secrets.CD_API_REFS_BUCKET_NAME }} \
-          ./scripts/generatedocc.sh "$VERSION" ${{ matrix.job }} ${{ strategy.job-total }} ${{ env.IGNORE }}
+          ./scripts/generatedocc.sh "$VERSION" ${{ matrix.job }} ${{ strategy.job-total }} ${{ env.IGNORE }} ${{ 1 }}
+      - name: Generate smithy-swift docs
+        run: |
+          cd ../smithy-swift \
+          ./../aws-sdk-swift/scripts/generatedocc.sh "$VERSION" ${{ matrix.job }} ${{ strategy.job-total }} ${{ env.IGNORE }} ${{ 0 }} \
+          cd ../aws-sdk-swift
   update-latest:
     needs: generate-docs
     runs-on: ubuntu-latest

AWSSDKSwiftCLI/Sources/AWSCLIUtils/FileManager+Utils.swift

@@ -36,6 +36,17 @@ public extension FileManager {
             .filter { !$0.hasPrefix(".") }
     }
 
+    /// Returns the list of Smithy runtime modules within `../smithy-swift/Sources/Core`
+    ///
+    /// - Returns: The list of Smithy runtime modules.
+    func getSmithyRuntimeModules() throws -> [String] {
+        try FileManager.default
+            .contentsOfDirectory(atPath: "../smithy-swift/Sources")
+            .sorted()
+            .filter { $0 != "libxml2" } // Ignore libxml module
+            .filter { !$0.hasPrefix(".") }
+    }
+
     /// Returns the list of AWS runtime modules within `Sources/Core`
     ///
     /// - Returns: The list of AWS runtime modules.

AWSSDKSwiftCLI/Sources/AWSSDKSwiftCLI/Commands/AWSSDKSwiftCLI/Subcommands/GenerateDocIndex.swift

@@ -34,9 +34,14 @@ struct GenerateDocIndexCommand: ParsableCommand {
     /// - Returns: The contents of the generated doc index.
     func generateDocIndexContents() throws -> String {
         let services = try resolveServices()
+        let smithyRuntimeModules = try resolveSmithyRuntimeModules()
         let awsRuntimeModules = try resolveAWSRuntimeModules()
         log("Creating doc index contents...")
-        let contents = try DocIndexBuilder(services: services, awsRuntimeModules: awsRuntimeModules).build()
+        let contents = try DocIndexBuilder(
+            services: services,
+            smithyRuntimeModules: smithyRuntimeModules,
+            awsRuntimeModules: awsRuntimeModules
+        ).build()
         log("Successfully created doc index contents")
         return contents
     }
@@ -70,6 +75,18 @@ struct GenerateDocIndexCommand: ParsableCommand {
         return resolvedServices
     }
 
+    /// Returns the list of Smithy runtime modules within `../smithy-swift/Sources/Core` to include in the doc index.
+    ///
+    /// - Returns: The list of Smithy runtime moduls to include in the doc index
+    func resolveSmithyRuntimeModules() throws -> [String] {
+        log("Resolving Smithy runtime modules...")
+        let resolvedSmithyRuntimeModules: [String]
+        log("Using list of Smithy runtime modules that exist within ../smithy-swift/Sources/Core")
+        resolvedSmithyRuntimeModules = try FileManager.default.getSmithyRuntimeModules()
+        log("Resolved list of Smithy runtime modules: \(resolvedSmithyRuntimeModules.count)")
+        return resolvedSmithyRuntimeModules
+    }
+
     /// Returns the list of AWS runtime modules within `Sources/Core` to include in the doc index.
     ///
     /// - Returns: The list of AWS runtime moduls to include in the doc index

AWSSDKSwiftCLI/Sources/AWSSDKSwiftCLI/Models/DocIndexBuilder.swift

@@ -16,11 +16,13 @@ struct DocIndexBuilder {
     }
 
     let services: [String]
+    let smithyRuntimeModules: [String]
     let awsRuntimeModules: [String]
     let baseDocIndexContents: () throws -> String
 
-    init(services: [String], awsRuntimeModules: [String]) {
+    init(services: [String], smithyRuntimeModules: [String], awsRuntimeModules: [String]) {
         self.services = services
+        self.smithyRuntimeModules = smithyRuntimeModules
         self.awsRuntimeModules = awsRuntimeModules
         self.baseDocIndexContents = {
             // Returns the contents of the base doc index stored in the bundle at `Resources/DocIndex.Base.md`
@@ -58,6 +60,8 @@ struct DocIndexBuilder {
     /// Builds all the generated package manifest content
     private func buildGeneratedContent() -> String {
         let contents = [
+            buildSmithyRuntimeModuleIndex(),
+            "",
             buildAWSRuntimeModuleIndex(),
             "",
             buildServiceIndex(),
@@ -66,6 +70,17 @@ struct DocIndexBuilder {
         return contents.joined(separator: .newline)
     }
 
+    /// Returns markdown links to Smithy module documentations
+    ///
+    /// - Returns: List of markdown links to Smithy module documentations
+    private func buildSmithyRuntimeModuleIndex() -> String {
+        let header = "## Smithy Runtime Module Documentation\n\n"
+        return header + smithyRuntimeModules.map { module in
+            let urlModule = module.lowercased(with: Locale(identifier: "en_US_POSIX"))
+            return "[\(module)](../../../../../swift/api/\(urlModule)/latest)\n"
+        }.joined(separator: "\n")
+    }
+
     /// Returns markdown links to AWS module documentations
     ///
     /// - Returns: List of markdown links to AWS module documentations

scripts/generatedocc.sh

@@ -75,6 +75,8 @@ TOTAL_JOBS="$3"
 # convert comma separated ignore list to array
 IGNORE=($(echo $4 | tr ',' '\n'))
 
+IS_AWS="$5"
+
 echo "Finding package names, unquoting names, sorting"
 packages=$(swift package dump-package | jq '.products[].name' | sed 's/"//g' | sort)
 
@@ -101,7 +103,7 @@ done
 
 # Generate an index with the current version, and
 # the literal version "latest"
-if [ $CURRENT_JOB -eq 0 ]; then
+if [ $CURRENT_JOB -eq 0 -a $IS_AWS -eq 1 ]; then
   generateDocs "AWSSDKForSwift" "$VERSION"
   generateDocs "AWSSDKForSwift" "latest"
 fi