Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

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

Merged
merged 9 commits into from
Aug 7, 2024
18 changes: 15 additions & 3 deletions .github/workflows/generate-documentation.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand All @@ -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
Expand Down
11 changes: 11 additions & 0 deletions AWSSDKSwiftCLI/Sources/AWSCLIUtils/FileManager+Utils.swift
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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
}
Expand Down Expand Up @@ -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
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down Expand Up @@ -58,6 +60,8 @@ struct DocIndexBuilder {
/// Builds all the generated package manifest content
private func buildGeneratedContent() -> String {
let contents = [
buildSmithyRuntimeModuleIndex(),
"",
buildAWSRuntimeModuleIndex(),
"",
buildServiceIndex(),
Expand All @@ -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
Expand Down
4 changes: 3 additions & 1 deletion scripts/generatedocc.sh
Original file line number Diff line number Diff line change
Expand Up @@ -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)

Expand All @@ -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
Loading