[doc] Getting Started documentation and tutorial

[sebsto]

This is proposal for a getting started documentation and step-by-step tutorial. This complements and replaces the original PR made by @fabianfett (https://github.com/swift-server/swift-aws-lambda-runtime/pull/261)

Motivation:

Provide a step-by-step tutorials to help new comers to get started with the Swift AWS Lambda Runtime

Modifications:

• create a top level documentation page for package AWSLambdaRuntimeCore. It contains a brief introduction to the project copied from the main README file) and links to other parts
• a getting started guide for the impatient, with just top-level instructions
• a step-by-step tutorial based on Swift Docs @Tutorial format

Result:

There is a getting started documentation ! You can see a preview at this ephemeral address : https://staging.stormacq.com/lambda-runtime-doc/documentation/awslambdaruntimecore/

[tomerd]

cc @bitjammer

[tomerd]

cc @Joannis

[tomerd]

this is awesome!

[tomerd]

@sebsto is this ready to be merged? its a great addition!

[tomerd]

@swift-server-bot add to allowlist

[sebsto]

@tomerd I am on PTO - hence the delay to answer questions. Yes, it is good for me and ready to publish

[sebsto]

Hello @tomerd what is the blocker for this one and how can I help to release it ?

[tomerd]

@sebsto no blocker, was confirming this was ready. looks like one CI job is not happy, but lets marge once green

[tomerd]

@swift-server-bot test this please

[sebsto]

I was inquiring about the failed CI Job :-) Looks like the soundness.sh script fails because swiftformat has not been applied.

But when I run swiftformat it updates many files that are not part of this PR ?

➜  swift-aws-lambda-runtime git:(sebsto/getting-started-doc) ✗ git status --porcelain
 M Examples/Foundation/Lambda.swift
 M Examples/LocalDebugging/MyApp/MyApp/ContentView.swift
 M Sources/AWSLambdaRuntimeCore/ControlPlaneRequest.swift
 M Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-02-01-package.swift
 M Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-02-02-package.swift
 M Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-02-04-package.swift
 M Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-02-05-package.swift
 M Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-01-main.swift
 M Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-02-main.swift
 M Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-03-main.swift
 M Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-04-main.swift
 M Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-05-main.swift
 M Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-06-main.swift
 M Sources/AWSLambdaRuntimeCore/HTTPClient.swift
 M Sources/AWSLambdaRuntimeCore/Lambda+LocalServer.swift
 M Sources/AWSLambdaRuntimeCore/Lambda.swift
 M Sources/AWSLambdaRuntimeCore/LambdaConfiguration.swift
 M Sources/AWSLambdaRuntimeCore/LambdaHandler.swift
 M Sources/AWSLambdaRuntimeCore/LambdaRequestID.swift
 M Sources/AWSLambdaRuntimeCore/LambdaRunner.swift
 M Sources/AWSLambdaRuntimeCore/LambdaRuntime.swift
 M Sources/AWSLambdaRuntimeCore/LambdaRuntimeClient.swift
 M Sources/AWSLambdaRuntimeCore/Terminator.swift
 M Sources/AWSLambdaRuntimeCore/Utils.swift
 M Sources/MockServer/main.swift
 M Tests/AWSLambdaRuntimeCoreTests/MockLambdaServer.swift
 M Tests/AWSLambdaRuntimeCoreTests/Utils.swift

Should I commit those as well ?

[tomerd]

try to run in docker install of installing swift-format locally, as you may be using a different version than the one we use

docker-compose -f docker/docker-compose.yaml -f docker/docker-compose.al2.58.yaml run soundness

[sebsto]

@tomerd thank you swiftformat is now OK. But soundness fails because the code snippets in the tutorial part do not have the license header file.

I think adding these to these code snippets will reduce the lisibility of the tutorial. soundness script makes no difference between source code file and code snippets from the doc, they all are *.swift

Can I modify soudness to skip files in the documentation directories ?

[tomerd]

I think adding these to these code snippets will reduce the lisibility of the tutorial.

where would they be visible?

[sebsto]

I think adding these to these code snippets will reduce the lisibility of the tutorial.

where would they be visible?

These are visible on the tutorial web page. The tutorial shows code incrementally, step by step, as reader scrolls down. Each step is a separate .swift file.

See screenshot attached.

[sebsto]

[sebsto]

Also, the core runtime does not compile on Swift 5.9 or Swift nightly. This should be fixed on the main branch.

15:48:54 /code/Sources/AWSLambdaRuntimeCore/LambdaContext.swift:15:17: remark: '@preconcurrency' attribute on module 'Dispatch' is unused
15:48:54 @preconcurrency import Dispatch
15:48:54 ~~~~~~~~~~~~~~~~^
15:48:54 [282/295] Compiling AWSLambdaRuntimeCore LambdaContext.swift
15:48:54 /code/Sources/AWSLambdaRuntimeCore/LambdaContext.swift:15:17: remark: '@preconcurrency' attribute on module 'Dispatch' is unused
15:48:54 @preconcurrency import Dispatch
15:48:54 ~~~~~~~~~~~~~~~~^
15:48:54 [283/295] Compiling AWSLambdaRuntimeCore Lambda+String.swift
15:48:54 /code/Sources/AWSLambdaRuntimeCore/Lambda.swift:88:23: error: 'install()' is deprecated: This is no longer needed in Swift 5.9
15:48:54             Backtrace.install()
15:48:54                       ^
15:48:54 [284/295] Compiling AWSLambdaRuntimeCore Lambda.swift
15:48:54 /code/Sources/AWSLambdaRuntimeCore/Lambda.swift:88:23: error: 'install()' is deprecated: This is no longer needed in Swift 5.9
15:48:54             Backtrace.install()
15:48:54                       ^
15:48:54 error: fatalError
15:48:54 error: fatalError

[tomerd]

These are visible on the tutorial web page.

right, but do license header show up as well? is there no way to filter them from DocC?

cc @bitjammer

[tomerd]

Also, the core runtime does not compile on Swift 5.9 or Swift nightly. This should be fixed on the main branch.

yes, that should be done in a separate PR

[sebsto]

Also, the core runtime does not compile on Swift 5.9 or Swift nightly. This should be fixed on the main branch.

yes, that should be done in a separate PR

I just opened https://github.com/swift-server/swift-aws-lambda-runtime/issues/304

[sebsto]

These are visible on the tutorial web page.

right, but do license header show up as well? is there no way to filter them from DocC?

cc @bitjammer

The code visible in the tutorial is assembled from individual *.swift files, one file for each code snippet. I choose to not include the license header file in these *.swift files to keep the code snippets that are visible on the tutorial web page clean.

Problem : soundness script checks for the presence of the header in all swift files (it uses this command : find . -name '*.swift' -o -name '*.c' -o -name '*.h')

Proposed solution : add an exception for *.swift files inside *.docc folders

git diff scripts/soundness.sh 
diff --git a/scripts/soundness.sh b/scripts/soundness.sh
index bd321f6..353359d 100755
--- a/scripts/soundness.sh
+++ b/scripts/soundness.sh
@@ -130,6 +130,7 @@ EOF
     find . \
       \( \! -path '*/.build/*' -a \
       \( \! -path '*/.git/*' \) -a \
+      \( \! -path '*/Documentation.docc/*' \) -a \
       \( "${matching_files[@]}" \) -a \
       \( \! \( "${exceptions[@]}" \) \) \) | while read line; do
       if [[ "$(cat "$line" | replace_acceptable_years | head -n $expected_lines | shasum)" != "$expected_sha" ]]; then

[tomerd]

Proposed solution : add an exception for .swift files inside .docc folders

I think that would be fine if we cannot find a way to tell DocC to ignore the license headers

cc @franklinsch

[tomerd]

5.9 wanring fix: https://github.com/swift-server/swift-aws-lambda-runtime/pull/305

[bitjammer]

I don't believe there is a way to hide regions of code in tutorials. They use a different feature from "snippets", which do have different mechanisms for hiding regions of code.

[sebsto]

Will be able to merge when https://github.com/swift-server/swift-aws-lambda-runtime/pull/307 is approved

[sebsto]

@swift-server-bot test this please

[sebsto]

@tomerd thank you for merging https://github.com/swift-server/swift-aws-lambda-runtime/pull/307, this PR is now ready to merge.