[Question] Can DocC remove license headers from source code file

[sebsto]

Expected behavior

Source code files that are part of the documentation should not have the required license header, that would make tutorial and documentation harder to read.

Actual behavior

CI script scripts/soundness.sh checks for license headers in ALL source files.

There are two possibles solutions :

1. (preferred) add the required license header files to all source code snippet in the doc and tell DocC to ignore the header file when generating the HTML page. (I asked the question to on the DocC slack channel and wait for a response)

2. modify scripts/soundness.sh to exclude Documentation.docc folders for the license header check.

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

Steps to reproduce

1. Add a source snippet as a .swift file in the documentation
2. Run docker-compose -f docker/docker-compose.yaml -f docker/docker-compose.al2.58.yaml run soundness

Result :

[+] Creating 2/0
 ✔ Network docker_default            Created                                                                                                               0.0s 
 ✔ Container docker-runtime-setup-1  Created                                                                                                               0.0s 
[+] Running 1/1
 ✔ Container docker-runtime-setup-1  Started                                                                                                               0.2s 
=> Checking for unacceptable language... okay.
=> Checking format... okay.
=> Checking license headers
   * swift-or-c... missing headers in file './Sources/AWSLambdaRuntimeCore/Documentation.docc/Resources/code/03-03-05-main.swift'!
--- /dev/fd/63  2023-09-08 16:10:11.789846001 +0000
+++ /tmp/.swift-aws-lambda-soundness_feXc5A 2023-09-08 16:10:10.580846000 +0000
@@ -1,13 +1,13 @@
-import AWSLambdaRuntime
-
-struct Input: Codable {
-    let number: Double
-}
-
-struct Number: Codable {
-    let result: Double
-}
-
-@main
-struct SquareNumberHandler: SimpleLambdaHandler {
-    typealias Event = Input
+//===----------------------------------------------------------------------===//
+//
+// This source file is part of the SwiftAWSLambdaRuntime open source project
+//
+// Copyright (c) YEARS Apple Inc. and the SwiftAWSLambdaRuntime project authors
+// Licensed under Apache License v2.0
+//
+// See LICENSE.txt for license information
+// See CONTRIBUTORS.txt for the list of SwiftAWSLambdaRuntime project authors
+//
+// SPDX-License-Identifier: Apache-2.0
+//
+//===----------------------------------------------------------------------===//

If possible, minimal yet complete reproducer code (or URL to code)

https://github.com/sebsto/swift-aws-lambda-runtime/tree/sebsto/getting-started-doc

What version of this project (swift-aws-lambda-runtime) are you using?

1.0.0-alpha-0.1

Swift version

n/a

Amazon Linux 2 docker image version

n/a

[sebsto]

This is blocking https://github.com/swift-server/swift-aws-lambda-runtime/pull/300

[sebsto]

According to this message, docc does not allow to remove or hide comments or snippets before generating the HTML.

Unfortunately this isn’t possible today. I think it would make sense to add support for hiding regions of code from tutorial code files (likely inspired by what is used for Snippets) but I wouldn’t want to block your work on this. I’d suggest you file a feature request on the Swift-DocC repo asking for this support, and then just link to it in your swift-aws-lambda PR where you skip the .docc directory. Alternatively, you could add some kind of transformation step that strips the comments before invoking docc, but I could see that getting messy.

Based on this, I will propose a PR to change the behavior of scripts/soundness.sh

[sebsto]

Will be fixed by https://github.com/swift-server/swift-aws-lambda-runtime/pull/307

[sebsto]

closing now that https://github.com/swift-server/swift-aws-lambda-runtime/pull/307 is merged