From 58031f8a8b85763dbfef5348765b905c7286e9da Mon Sep 17 00:00:00 2001 From: Cory Benfield Date: Tue, 11 Apr 2023 11:49:47 +0100 Subject: [PATCH] Fix documentation and add infrastructure for CI-ing it --- .../Docs.docc/index.md | 8 ++++--- .../StructuredFieldValues/Docs.docc/index.md | 8 ++++--- docker/docker-compose.2004.55.yaml | 3 +++ docker/docker-compose.2004.56.yaml | 3 +++ docker/docker-compose.2204.57.yaml | 3 +++ docker/docker-compose.2204.58.yaml | 3 +++ docker/docker-compose.2204.main.yaml | 3 +++ docker/docker-compose.yaml | 4 ++++ scripts/check-docs.sh | 23 +++++++++++++++++++ scripts/soundness.sh | 2 +- 10 files changed, 53 insertions(+), 7 deletions(-) create mode 100755 scripts/check-docs.sh diff --git a/Sources/RawStructuredFieldValues/Docs.docc/index.md b/Sources/RawStructuredFieldValues/Docs.docc/index.md index 883e6fa..42eb09e 100644 --- a/Sources/RawStructuredFieldValues/Docs.docc/index.md +++ b/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. diff --git a/Sources/StructuredFieldValues/Docs.docc/index.md b/Sources/StructuredFieldValues/Docs.docc/index.md index c714900..574b972 100644 --- a/Sources/StructuredFieldValues/Docs.docc/index.md +++ b/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: diff --git a/docker/docker-compose.2004.55.yaml b/docker/docker-compose.2004.55.yaml index d43faad..8787f0e 100644 --- a/docker/docker-compose.2004.55.yaml +++ b/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 diff --git a/docker/docker-compose.2004.56.yaml b/docker/docker-compose.2004.56.yaml index fe21b9f..2a4ef3e 100644 --- a/docker/docker-compose.2004.56.yaml +++ b/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 diff --git a/docker/docker-compose.2204.57.yaml b/docker/docker-compose.2204.57.yaml index fb05c49..3b34cf8 100644 --- a/docker/docker-compose.2204.57.yaml +++ b/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 diff --git a/docker/docker-compose.2204.58.yaml b/docker/docker-compose.2204.58.yaml index d9d8c62..bb15654 100644 --- a/docker/docker-compose.2204.58.yaml +++ b/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: diff --git a/docker/docker-compose.2204.main.yaml b/docker/docker-compose.2204.main.yaml index 25fcd5e..2212dfa 100644 --- a/docker/docker-compose.2204.main.yaml +++ b/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: diff --git a/docker/docker-compose.yaml b/docker/docker-compose.yaml index be8a7b5..1c62227 100644 --- a/docker/docker-compose.yaml +++ b/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-}" diff --git a/scripts/check-docs.sh b/scripts/check-docs.sh new file mode 100755 index 0000000..9405b7e --- /dev/null +++ b/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 diff --git a/scripts/soundness.sh b/scripts/soundness.sh index 59e4750..6c0aad2 100755 --- a/scripts/soundness.sh +++ b/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/' }