Add docc support and publish documentation to GitHub pages (apple#137)

* Move Guides into docc base location

* Add Github gh-page support

* Conditionally add docc-plugin dependency

* Temp skip AsyncSequenceValidation target

Author: Kyle-Ye

Package.swift

@@ -41,3 +41,18 @@ let package = Package(
       ]),
   ]
 )
+
+#if canImport(Darwin)
+import Darwin
+let buildingDocs = getenv("BUILDING_FOR_DOCUMENTATION_GENERATION") != nil
+#elseif canImport(Glibc)
+import Glibc
+let buildingDocs = getenv("BUILDING_FOR_DOCUMENTATION_GENERATION") != nil
+#else
+let buildingDocs = false
+#endif
+
+// Only require the docc plugin when building documentation
+package.dependencies += buildingDocs ? [
+  .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.0.0"),
+] : []

Sources/AsyncAlgorithms/AsyncAlgorithms.docc/AsyncAlgorithms.md

@@ -0,0 +1,36 @@
+# ``AsyncAlgorithms``
+
+**Swift Async Algorithms** is an open-source package of asynchronous sequence and advanced algorithms that involve concurrency, along with their related types.
+
+## Overview
+
+This package has three main goals:
+
+- First-class integration with `async/await`
+- Provide a home for time-based algorithms
+- Be cross-platform and open source
+
+## Topics
+
+### Getting Started
+
+- <doc:AdjacentPairs>
+- <doc:BufferedBytes>
+- <doc:Chain>
+- <doc:Channel>
+- <doc:Chunked>
+- <doc:Collections>
+- <doc:CombineLatest>
+- <doc:Compacted>
+- <doc:Debounce>
+- <doc:Effects>
+- <doc:Intersperse>
+- <doc:Joined>
+- <doc:Lazy>
+- <doc:Merge>
+- <doc:Reductions>
+- <doc:RemoveDuplicates>
+- <doc:Select>
+- <doc:Throttle>
+- <doc:Timer>
+- <doc:Zip>

Guides/AdjacentPairs.md Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/AdjacentPairs.md

@@ -50,5 +50,4 @@ This means that `withTaskGroup` is highly suited to run work in parallel, wherea
 ## Future Directions
 
 
-
 ## Credits/Inspiration

Guides/BufferedBytes.md Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/BufferedBytes.md

@@ -0,0 +1,14 @@
+# ``AsyncSequenceValidation``
+
+
+## Overview
+
+Testing is a critical area of focus for any package to make it robust, catch bugs, and explain the expected behaviors in a documented manner. Testing things that are asynchronous can be difficult, testing things that are asynchronous multiple times can be even more difficult.
+
+Types that implement `AsyncSequence` can often be described in deterministic actions given particular inputs. For the inputs, the events can be described as a discrete set: values, errors being thrown, the terminal state of returning a `nil` value from the iterator, or advancing in time and not doing anything. Likewise, the expected output has a discrete set of events: values, errors being caught, the terminal state of receiving a `nil` value from the iterator, or advancing in time and not doing anything. 
+
+## Topics
+
+### Getting Started
+
+- <doc:Validation>

Guides/Chain.md Sources/AsyncAlgorithms/AsyncAlgorithms.docc/Guides/Chain.md

@@ -0,0 +1,71 @@
+#!/bin/bash
+#
+# This source file is part of the Swift.org open source project
+#
+# Copyright (c) 2022 Apple Inc. and the Swift project authors
+# Licensed under Apache License v2.0 with Runtime Library Exception
+#
+# See https://swift.org/LICENSE.txt for license information
+# See https://swift.org/CONTRIBUTORS.txt for Swift project authors
+#
+# Updates the GitHub Pages documentation site thats published from the 'docs'
+# subdirectory in the 'gh-pages' branch of this repository.
+#
+# This script should be run by someone with commit access to the 'gh-pages' branch
+# at a regular frequency so that the documentation content on the GitHub Pages site
+# is up-to-date with the content in this repo.
+#
+
+export BUILDING_FOR_DOCUMENTATION_GENERATION=1
+
+set -eu
+
+# A `realpath` alternative using the default C implementation.
+filepath() {
+  [[ $1 = /* ]] && echo "$1" || echo "$PWD/${1#./}"
+}
+
+SWIFT_ASYNC_ALGORITHMS_ROOT="$(dirname $(dirname $(filepath $0)))"
+
+ASYNC_ALGORITHMS_BUILD_DIR="$SWIFT_ASYNC_ALGORITHMS_ROOT"/.build/async-algorithms-gh-pages-build
+
+# Set current directory to the repository root
+cd "$SWIFT_ASYNC_ALGORITHMS_ROOT"
+
+# Use git worktree to checkout the gh-pages branch of this repository in a gh-pages sub-directory
+git fetch
+git worktree add --checkout gh-pages origin/gh-pages
+
+# Pretty print DocC JSON output so that it can be consistently diffed between commits
+export DOCC_JSON_PRETTYPRINT="YES"
+
+# Generate documentation for the 'AsyncAlgorithms' target and output it
+# to the /docs subdirectory in the gh-pages worktree directory.
+swift package \
+    --allow-writing-to-directory "$SWIFT_ASYNC_ALGORITHMS_ROOT/gh-pages/docs" \
+    generate-documentation \
+    --target AsyncAlgorithms \
+    --disable-indexing \
+    --transform-for-static-hosting \
+    --hosting-base-path swift-async-algorithms \
+    --output-path "$SWIFT_ASYNC_ALGORITHMS_ROOT/gh-pages/docs"
+
+# Save the current commit we've just built documentation from in a variable
+CURRENT_COMMIT_HASH=`git rev-parse --short HEAD`
+
+# Commit and push our changes to the gh-pages branch
+cd gh-pages
+git add docs
+
+if [ -n "$(git status --porcelain)" ]; then
+    echo "Documentation changes found. Commiting the changes to the 'gh-pages' branch and pushing to origin."
+    git commit -m "Update GitHub Pages documentation site to $CURRENT_COMMIT_HASH"
+    git push origin HEAD:gh-pages
+else
+  # No changes found, nothing to commit.
+  echo "No documentation changes found."
+fi
+
+# Delete the git worktree we created
+cd ..
+git worktree remove gh-pages