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

Author: Lukasa

Sources/RawStructuredFieldValues/Docs.docc/index.md

@@ -4,11 +4,13 @@ A Swift implementation of the HTTP Structured Header Field Value specification.
 
 Provides parsing and serialization facilities for structured header field values.
 
-## About Structured Header Field Values
+## Overview
+
+### About Structured Header Field Values
 
 HTTP Structured Header Field Values are a HTTP extension recorded in [RFC 8941](https://www.rfc-editor.org/rfc/rfc8941.html). They provide a set of data types and algorithms for handling HTTP header field values in a consistent way, allowing a single parser and serializer to handle a wide range of header field values.
 
-## Swift HTTP Structured Header Field Values
+### Swift HTTP Structured Header Field Values
 
 This package provides a parser and serializer that implement RFC 8941. They are entirely complete, able to handle all valid HTTP structured header field values.
 
@@ -22,7 +24,7 @@ The upper-level module, `StructuredFieldValues`, brings along the `Encoder` and
 
 In most cases users should prefer to use `StructuredFieldValues` unless they know they need the performance advantages of `RawStructuredFieldValues`. The experience will be much better.
 
-## Working with Structured Header Field Values
+### Working with Structured Header Field Values
 
 `RawStructuredFieldValues` has a powerful API for working with structured header field values.
 

Sources/StructuredFieldValues/Docs.docc/index.md

@@ -4,11 +4,13 @@ A Swift implementation of the HTTP Structured Header Field Value specification.
 
 Provides parsing and serialization facilities for structured header field values, as well as implementations of `Encoder` and `Decoder` to allow using `Codable` data types as the payloads of HTTP structured header fields.
 
-## About Structured Header Field Values
+## Overview
+
+### About Structured Header Field Values
 
 HTTP Structured Header Field Values are a HTTP extension recorded in [RFC 8941](https://www.rfc-editor.org/rfc/rfc8941.html). They provide a set of data types and algorithms for handling HTTP header field values in a consistent way, allowing a single parser and serializer to handle a wide range of header field values.
 
-## Swift HTTP Structured Header Field Values
+### Swift HTTP Structured Header Field Values
 
 This package provides a parser and serializer that implement RFC 8941. They are entirely complete, able to handle all valid HTTP structured header field values. This package also provides `Encoder` and `Decoder` objects for working with Codable in Swift. This allows rapid prototyping and experimentation with HTTP structured header field values, as well as interaction with the wider Swift Codable community.
 
@@ -18,7 +20,7 @@ This module, `StructuredFieldValues`, use the related module `RawStructuredField
 
 Users who have performance problems with this solution or have specific representational needs should investigate `RawStructuredFieldValues`.
 
-## Working with Structured Header Field Values
+### Working with Structured Header Field Values
 
 `StructuredFieldValues` has a simple, easy-to-use high-level API for working with structured header field values. To begin with, let's consider the [HTTP Client Hints specification](https://www.rfc-editor.org/rfc/rfc8942.html). This defines the following new header field:
 

docker/docker-compose.2004.55.yaml

@@ -12,6 +12,9 @@ services:
   unit-tests:
     image: swift-http-structured-headers:20.04-5.5
 
+  documentation-check:
+    image: swift-http-structured-headers:20.04-5.5
+
   test:
     image: swift-http-structured-headers:20.04-5.5
 

docker/docker-compose.2004.56.yaml

@@ -12,6 +12,9 @@ services:
   unit-tests:
     image: swift-http-structured-headers:20.04-5.6
 
+  documentation-check:
+    image: swift-http-structured-headers:20.04-5.6
+
   test:
     image: swift-http-structured-headers:20.04-5.6
 

docker/docker-compose.2204.57.yaml

@@ -12,6 +12,9 @@ services:
   unit-tests:
     image: swift-http-structured-headers:22.04-5.7
 
+  documentation-check:
+    image: swift-http-structured-headers:22.04-5.7
+
   test:
     image: swift-http-structured-headers:22.04-5.7
 

docker/docker-compose.2204.58.yaml

@@ -12,6 +12,9 @@ services:
   unit-tests:
     image: swift-http-structured-headers:22.04-5.8
 
+  documentation-check:
+    image: swift-http-structured-headers:22.04-5.8
+
   test:
     image: swift-http-structured-headers:22.04-5.8
     environment:

docker/docker-compose.2204.main.yaml

@@ -12,6 +12,9 @@ services:
   unit-tests:
     image: swift-http-structured-headers:22.04-main
 
+  documentation-check:
+    image: swift-http-structured-headers:22.04-main
+
   test:
     image: swift-http-structured-headers:22.04-main
     environment:

docker/docker-compose.yaml

@@ -30,6 +30,10 @@ services:
     <<: *common
     command: /bin/bash -xcl "swift test --enable-test-discovery -Xswiftc -warnings-as-errors"
 
+  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-} $${IMPORT_CHECK_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

@@ -17,7 +17,7 @@ set -eu
 here="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
 function replace_acceptable_years() {
     # this needs to replace all acceptable forms with 'YEARS'
-    sed  -e 's/202[01]-202[012]/YEARS/' -e 's/202[012]/YEARS/'
+    sed  -e 's/202[0123]-202[0123]/YEARS/' -e 's/202[0123]/YEARS/'
 }