Fix documentation and add infrastructure for CI-ing it (#169)

* Fix documentation and add infrastructure for CI-ing it

* Add 2023 to soundness

Sources/NIOTransportServices/Docs.docc/index.md

@@ -2,7 +2,9 @@
 
 Extensions for SwiftNIO to support Apple platforms as first-class citizens.
 
-## About NIO Transport Services
+## Overview
+
+### About NIO Transport Services
 
 NIO Transport Services is an extension to SwiftNIO that provides first-class support for Apple platforms by using [Network.framework](https://developer.apple.com/documentation/network) to provide network connectivity, and [Dispatch](https://developer.apple.com/documentation/dispatch) to provide concurrency. NIOTS provides an alternative [EventLoop](https://swiftpackageindex.com/apple/swift-nio/main/documentation/niocore/eventloop), [EventLoopGroup](https://swiftpackageindex.com/apple/swift-nio/main/documentation/niocore/eventloopgroup), and several alternative [Channels](https://swiftpackageindex.com/apple/swift-nio/main/documentation/niocore/channel) and Bootstraps.
 
@@ -10,11 +12,11 @@ In addition to providing first-class support for Apple platforms, NIO Transport
 
 All regular NIO applications should work just fine with NIO Transport Services, simply by changing the event loops and bootstraps in use.
 
-## Why Transport Services?
+### Why Transport Services?
 
 Network.framework is Apple's reference implementation of the [proposed post-sockets API](https://datatracker.ietf.org/wg/taps/charter/) that is currently being worked on by the Transport Services Working Group (taps) of the IETF. To indicate the proposed long-term future of interfaces like Network.framework, we decided to call this module NIOTransportServices. Also, NIONetworkFramework didn't appeal to us much as a name.
 
-## How to Use NIO Transport Services
+### How to Use NIO Transport Services
 
 NIO Transport Services primarily uses SwiftPM as its build tool, so we recommend using that as well. If you want to depend on NIO Transport Services in your own project, it's as simple as adding a dependencies clause to your Package.swift:
 
@@ -28,7 +30,7 @@ and then adding the `NIOTransportServices` module to your target dependencies.
 
 If your project is set up as an Xcode project and you're using Xcode 11+, you can add NIO Transport Services as a dependency to your Xcode project by clicking File -> Swift Packages -> Add Package Dependency. In the upcoming dialog, please enter `https://github.com/apple/swift-nio-transport-services.git` and click Next twice. Finally, make sure `NIOTransportServices` is selected and click finish. Now will be able to `import NIOTransportServices` in your project.
 
-### Supported Platforms
+#### Supported Platforms
 
 NIOTransportServices is supported where Network.framework is supported: macOS
 10.14+, iOS 12+, tvOS 12+, and watchOS 6+.
@@ -41,12 +43,12 @@ NIOTransportServices can be built on macOS 10.12+, iOS 10+, tvOS 10+, watchOS
 6+ and Linux but is only functionally useful on macOS 10.14+, iOS 12+, tvOS 12+
 and watchOS 6+.
 
-## Versioning
+### Versioning
 
 Just like the rest of the SwiftNIO family, `swift-nio-transport-services` follows [SemVer 2.0.0](https://semver.org/#semantic-versioning-200) with a separate document
 declaring [SwiftNIO's Public API](https://github.com/apple/swift-nio/blob/main/docs/public-api.md).
 
-### NIO Transport Services 1.x
+#### NIO Transport Services 1.x
 
 `swift-nio-transport-services` versions 1.x is part of the SwiftNIO 2 family of repositories and does not have any dependencies besides [`swift-nio`](https://github.com/apple/swift-nio), Swift 5.5.2, and an Apple OS supporting `Network.framework`. As the latest version, it lives on the [`main`](https://github.com/apple/swift-nio-transport-services) branch.
 
@@ -63,7 +65,7 @@ SwiftNIO Extras     | Minimum Swift Version
 `1.12.0 ..< 1.14.0` | 5.4
 `1.14.0 ...`        | 5.5.2
 
-### NIO Transport Services 0.x
+#### NIO Transport Services 0.x
 
 The legacy `swift-nio-transport-services` 0.x is part of the SwiftNIO 1 family of repositories and works with Swift 4.1 and newer. The source code can be found on the [`swift-nio-transport-services-swift-4-maintenance`](https://github.com/apple/swift-nio-transport-services/tree/swift-nio-transport-services-swift-4-maintenance) branch.
 

docker/docker-compose.2004.55.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "focal"
         swift_version: "5.5"
 
+  documentation-check:
+    image: swift-nio-transport-services:20.04-5.5
+
   test:
     image: swift-nio-transport-services:20.04-5.5
 

docker/docker-compose.2004.56.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "focal"
         swift_version: "5.6"
 
+  documentation-check:
+    image: swift-nio-transport-services:20.04-5.6
+
   test:
     image: swift-nio-transport-services:20.04-5.6
 

docker/docker-compose.2204.57.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "jammy"
         swift_version: "5.7"
 
+  documentation-check:
+    image: swift-nio-transport-services:22.04-5.7
+
   test:
     image: swift-nio-transport-services:22.04-5.7
 

docker/docker-compose.2204.58.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "jammy"
         base_image: "swiftlang/swift:nightly-5.8-jammy"
 
+  documentation-check:
+    image: swift-nio-transport-services:22.04-5.8
+
   test:
     image: swift-nio-transport-services:22.04-5.8
 

docker/docker-compose.2204.main.yaml

@@ -9,6 +9,9 @@ services:
         ubuntu_version: "jammy"
         base_image: "swiftlang/swift:nightly-main-jammy"
 
+  documentation-check:
+    image: swift-nio-transport-services:22.04-main
+
   test:
     image: swift-nio-transport-services:22.04-main
 

docker/docker-compose.yaml

@@ -26,6 +26,10 @@ services:
     <<: *common
     command: /bin/bash -xcl "./scripts/soundness.sh"
 
+  documentation-check:
+    <<: *common
+    command: /bin/bash -xcl "./scripts/check-docs.sh"
+
   test:
     <<: *common
     command: /bin/bash -xcl "swift test --enable-test-discovery -Xswiftc -warnings-as-errors $${SANITIZER_ARG-}"

scripts/check-docs.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+##===----------------------------------------------------------------------===##
+##
+## This source file is part of the SwiftNIO open source project
+##
+## Copyright (c) 2023 Apple Inc. and the SwiftNIO project authors
+## Licensed under Apache License v2.0
+##
+## See LICENSE.txt for license information
+## See CONTRIBUTORS.txt for the list of SwiftNIO project authors
+##
+## SPDX-License-Identifier: Apache-2.0
+##
+##===----------------------------------------------------------------------===##
+
+set -eu
+
+raw_targets=$(sed -E -n -e 's/^.* - documentation_targets: \[(.*)\].*$/\1/p' .spi.yml)
+targets=(${raw_targets//,/ })
+
+for target in "${targets[@]}"; do
+  swift package plugin generate-documentation --target "$target" --warnings-as-errors --analyze --level detailed
+done

scripts/soundness.sh

@@ -18,7 +18,7 @@ here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 
 function replace_acceptable_years() {
     # this needs to replace all acceptable forms with 'YEARS'
-    sed -e 's/20[12][789012]-20[12][89012]/YEARS/' -e 's/20[12][89012]/YEARS/'
+    sed -e 's/20[12][7890123]-20[12][890123]/YEARS/' -e 's/20[12][890123]/YEARS/'
 }
 
 # This checks for the umbrella NIO module.