Fix broken documentation (#2278)

~When looking at the documentation at SPI for this package, I noticed
that the latest published `1.X` release is `1.24.2`,
https://swiftpackageindex.com/grpc/grpc-swift/1.24.2/documentation/grpc.
I'm not sure if this is because stops tracking previous major versions,
once a newer major has been released (notice that `1.24.2` was the last
`1.X` release before `2.0.0`), or if there's some issue with the newer
`1.X` releases? For example, `GRPCCore` is listed in `spi.yml`, but that
target doesn't exist on `1.X`. See
#2279

The documentation for this package contains a few broken links, both
internal and external.

I updated all broken links, except for
https://github.com/grpc/grpc-swift/blob/release/1.x/docs/faqs.md?plain=1#L157
which points to a file that doesn't exist.
I also removed non-existing target `GRPCCore` from `.spi.yml`, and added
a link to SPI in the README.
Last, I removed some unused markdown links.

Co-authored-by: George Barnett <gbarnett@apple.com>

Author: samuelmurray

.spi.yml

@@ -1,4 +1,4 @@
 version: 1
 builder:
   configs:
-    - documentation_targets: [GRPC, GRPCReflectionService, protoc-gen-grpc-swift, GRPCCore]
+    - documentation_targets: [GRPC, GRPCReflectionService, protoc-gen-grpc-swift]

README.md

@@ -2,6 +2,7 @@
 
 This repository contains a gRPC code generator and runtime libraries for Swift.
 You can read more about gRPC on the [gRPC project's website][grpcio].
+Documentation is available on the [Swift Package Index][spi-grpc-swift].
 
 > [!IMPORTANT]  
 >  
@@ -39,4 +40,4 @@ Please get involved! See our [guidelines for contributing](CONTRIBUTING.md).
 
 [gh-grpc]: https://github.com/grpc/grpc
 [grpcio]: https://grpc.io
-[spi-grpc-swift-main]: https://swiftpackageindex.com/grpc/grpc-swift/main/documentation/grpccore
+[spi-grpc-swift]: https://swiftpackageindex.com/grpc/grpc-swift/release-1.x/documentation

SECURITY.md

@@ -39,7 +39,7 @@ with the [details usually included with bug reports][issue-template].
   and the [SSWG][sswg] will announce the vulnerability on the [Swift
   forums][swift-forums-sec].
 
-[issue-template]: https://github.com/grpc/grpc-swift/blob/main/.github/ISSUE_TEMPLATE/BUG_REPORT.md
+[issue-template]: https://github.com/grpc/grpc-swift/blob/release/1.x/.github/ISSUE_TEMPLATE/BUG_REPORT.md
 [sswg]: https://github.com/swift-server/sswg
 [sswg-security]: https://github.com/swift-server/sswg/blob/main/process/incubation.md#security-best-practices
 [swift-forums-sec]: https://forums.swift.org/c/server/security-updates/

Sources/GRPC/Docs.docc/index.md

@@ -110,19 +110,14 @@ Some of the examples are accompanied by tutorials, including:
 - Support for Apple Platforms and NIO Transport Services in
   [`docs/apple-platforms.md`][docs-apple]
 
-[docs-apple]: https://github.com/grpc/grpc-swift/tree/main/docs/apple-platforms.md
-[docs-plugin]: https://github.com/grpc/grpc-swift/tree/main/docs/plugin.md
-[docs-quickstart]: https://github.com/grpc/grpc-swift/tree/main/docs/quick-start.md
-[docs-tls]: https://github.com/grpc/grpc-swift/tree/main/docs/tls.md
-[docs-keepalive]: https://github.com/grpc/grpc-swift/tree/main/docs/keepalive.md
-[docs-tutorial]: https://github.com/grpc/grpc-swift/tree/main/docs/basic-tutorial.md
-[docs-interceptors-tutorial]: https://github.com/grpc/grpc-swift/tree/main/docs/interceptors-tutorial.md
-[grpc]: https://github.com/grpc/grpc
+[docs-apple]: https://github.com/grpc/grpc-swift/tree/release/1.x/docs/apple-platforms.md
+[docs-plugin]: https://github.com/grpc/grpc-swift/tree/release/1.x/docs/plugin.md
+[docs-quickstart]: https://github.com/grpc/grpc-swift/tree/release/1.x/docs/quick-start.md
+[docs-tls]: https://github.com/grpc/grpc-swift/tree/release/1.x/docs/tls.md
+[docs-keepalive]: https://github.com/grpc/grpc-swift/tree/release/1.x/docs/keepalive.md
+[docs-tutorial]: https://github.com/grpc/grpc-swift/tree/release/1.x/docs/basic-tutorial.md
+[docs-interceptors-tutorial]: https://github.com/grpc/grpc-swift/tree/release/1.x/docs/interceptors-tutorial.md
 [protobuf-releases]: https://github.com/protocolbuffers/protobuf/releases
 [swift-nio-platforms]: https://github.com/apple/swift-nio#supported-platforms
-[swift-nio]: https://github.com/apple/swift-nio
 [swift-protobuf]: https://github.com/apple/swift-protobuf
-[xcode-spm]: https://help.apple.com/xcode/mac/current/#/devb83d64851
-[branch-new]: https://github.com/grpc/grpc-swift/tree/main
-[branch-old]: https://github.com/grpc/grpc-swift/tree/cgrpc
-[examples]: https://github.com/grpc/grpc-swift/tree/main/Examples/v1
+[examples]: https://github.com/grpc/grpc-swift/tree/release/1.x/Examples/v1

Sources/GRPCReflectionService/Documentation.docc/ReflectionServiceTutorial.md

@@ -217,11 +217,10 @@ Note that when specifying a service, a method or a symbol, we have to use the fu
 [grpcurl-setup]: https://github.com/fullstorydev/grpcurl#grpcurl
 [grpcurl]: https://github.com/fullstorydev/grpcurl
 [grpc-cli]: https://github.com/grpc/grpc/blob/master/doc/command_line_tool.md
-[v1]: ../v1/reflection-v1.proto
-[v1alpha]: ../v1Alpha/reflection-v1alpha.proto
-[reflection-server]: ../../Examples/v1/ReflectionService/ReflectionServer.swift
+[v1]: ../../../Protos/upstream/grpc/reflection/v1/reflection.proto
+[v1alpha]: ../../../Protos/upstream/grpc/reflection/v1alpha/reflection.proto
+[reflection-server]: ../../../Examples/v1/ReflectionService/ReflectionServer.swift
 [helloworld-proto]: ../../Examples/v1/HelloWorld/Model/helloworld.proto
-[echo-proto]: ../../Examples/v1/Echo/Model/echo.proto
 [grpcurl-v188]: https://github.com/fullstorydev/grpcurl/releases/tag/v1.8.8
-[swiftpm-resources]: https://github.com/apple/swift-package-manager/blob/main/Documentation/PackageDescription.md#resource
+[swiftpm-resources]: https://github.com/swiftlang/swift-package-manager/blob/main/Sources/Runtimes/PackageDescription/PackageDescription.docc/PackageDescription.md
 [spm-plugin]: ../../protoc-gen-grpc-swift/Docs.docc/spm-plugin.md

docs/basic-tutorial.md

@@ -610,5 +610,4 @@ Follow the instructions in the Route Guide example directory
 [routeguide-readme]: ../Examples/v1/RouteGuide/README.md
 [routeguide-source]: ../Examples/v1/RouteGuide
 [run-protoc]: ../Protos/generate.sh
-[swift-protobuf-guide]: https://github.com/apple/swift-protobuf/blob/main/Documentation/API.md
 [swift-protobuf]: https://github.com/apple/swift-protobuf

docs/plugin.md

@@ -119,6 +119,5 @@ protoc <your proto> --grpc-swift_opt=Client=true,Server=false --grpc-swift_out=.
 ```
 
 [protocol-buffers]: https://developers.google.com/protocol-buffers/docs/overview
-[swift-protobuf-filenaming]: https://github.com/apple/swift-protobuf/blob/main/Documentation/PLUGIN.md#generation-option-filenaming---naming-of-generated-sources
 [swift-protobuf-module-mappings]: https://github.com/apple/swift-protobuf/blob/main/Documentation/PLUGIN.md#generation-option-protopathmodulemappings---swift-module-names-for-proto-paths
 [swift-protobuf-module-name]: https://github.com/apple/swift-protobuf/commit/9df381f72ff22062080d434e9c2f68e71ee44298#diff-1b08f0a80bd568509049d851b8d8af90d1f2db3cd8711eaba974b5380cd59bf3

docs/tls.md

@@ -90,6 +90,6 @@ a `String` using by using the UTF8 view on the string with the
 Refer to the [certificate][nio-ref-tlscert] or [private
 key][nio-ref-privatekey] documentation for more information.
 
-[nio-ref-privatekey]: https://apple.github.io/swift-nio-ssl/docs/current/NIOSSL/Classes/NIOSSLPrivateKey.html
-[nio-ref-tlscert]: https://apple.github.io/swift-nio-ssl/docs/current/NIOSSL/Classes/NIOSSLCertificate.html
-[nio-ref-tlsconfig]: https://apple.github.io/swift-nio-ssl/docs/current/NIOSSL/Structs/TLSConfiguration.html
+[nio-ref-privatekey]: https://swiftpackageindex.com/apple/swift-nio-ssl/documentation/niossl/niosslprivatekey
+[nio-ref-tlscert]: https://swiftpackageindex.com/apple/swift-nio-ssl/documentation/niossl/niosslcertificate
+[nio-ref-tlsconfig]: https://swiftpackageindex.com/apple/swift-nio-ssl/documentation/niossl/tlsconfiguration