Run docs in CI (#7544)

.github/workflows/docs.yml

@@ -0,0 +1,46 @@
+name: build
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+    types: [opened, labeled, unlabeled, synchronize]
+
+permissions:
+  contents: read
+
+env:
+  GRADLE_OPTS: "-Dorg.gradle.jvmargs=-Xmx4g -Dorg.gradle.daemon=false -Dkotlin.incremental=false"
+
+jobs:
+  test_docs:
+    permissions:
+      checks: write # for actions/upload-artifact
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Configure JDK
+        uses: actions/setup-java@v3
+        with:
+          distribution: 'zulu'
+          java-version: 11
+
+      - uses: actions/setup-python@v4
+        with:
+          python-version: 3.x
+
+      - run: pip install mkdocs-material mkdocs-redirects
+
+      - name: Generate Docs
+        run: ./test_docs.sh
+
+      - uses: actions/upload-artifact@v3
+        with:
+          name: docs
+          path: site/

.gitignore

@@ -35,3 +35,5 @@ docs/index.md
 
 # jenv
 /.java-version
+/site/
+/docs/changelogs/changelog.md

docs/features/https.md

@@ -15,7 +15,7 @@ Specific security vs. connectivity decisions are implemented by [ConnectionSpec]
  * `COMPATIBLE_TLS` is a secure configuration that connects to secure–but not current–HTTPS servers.
  * `CLEARTEXT` is an insecure configuration that is used for `http://` URLs.
 
-These loosely follow the model set in [Google Cloud Policies](https://cloud.google.com/load-balancing/docs/ssl-policies-concepts). We [track changes](tls_configuration_history.md) to this policy.
+These loosely follow the model set in [Google Cloud Policies](https://cloud.google.com/load-balancing/docs/ssl-policies-concepts). We [track changes](../security/tls_configuration_history.md) to this policy.
 
 By default, OkHttp will attempt a `MODERN_TLS` connection.  However by configuring the client connectionSpecs you can allow a fall back to `COMPATIBLE_TLS` connection if the modern configuration fails.
 
@@ -58,7 +58,7 @@ Caused by: javax.net.ssl.SSLProtocolException: SSL handshake aborted: ssl=0x7f27
 ```
 
 You can check a web server's configuration using [Qualys SSL Labs][qualys]. OkHttp's TLS
-configuration history is [tracked here](tls_configuration_history.md).
+configuration history is [tracked here](../features/tls_configuration_history.md).
 
 Applications expected to be installed on older Android devices should consider adopting the
 [Google Play Services’ ProviderInstaller][provider_installer]. This will increase security for users

test_docs.sh

@@ -0,0 +1,48 @@
+#!/bin/bash
+
+# The website is built using MkDocs with the Material theme.
+# https://squidfunk.github.io/mkdocs-material/
+# It requires Python to run.
+# Install the packages with the following command:
+# pip install mkdocs mkdocs-material mkdocs-redirects
+
+set -ex
+
+# Generate the API docs
+./gradlew \
+  :mockwebserver:dokkaGfm \
+  :okhttp-brotli:dokkaGfm \
+  :okhttp-dnsoverhttps:dokkaGfm \
+  :logging-interceptor:dokkaGfm \
+  :okhttp-sse:dokkaGfm \
+  :okhttp-tls:dokkaGfm \
+  :okhttp-urlconnection:dokkaGfm \
+  :okhttp:dokkaGfm
+
+# Dokka filenames like `-http-url/index.md` don't work well with MkDocs <title> tags.
+# Assign metadata to the file's first Markdown heading.
+# https://www.mkdocs.org/user-guide/writing-your-docs/#meta-data
+title_markdown_file() {
+  TITLE_PATTERN="s/^[#]+ *(.*)/title: \1 - OkHttp/"
+  echo "---"                                                     > "$1.fixed"
+  cat $1 | sed -E "$TITLE_PATTERN" | grep "title: " | head -n 1 >> "$1.fixed"
+  echo "---"                                                    >> "$1.fixed"
+  echo                                                          >> "$1.fixed"
+  cat $1                                                        >> "$1.fixed"
+  mv "$1.fixed" "$1"
+}
+
+set +x
+for MARKDOWN_FILE in $(find docs/4.x -name '*.md'); do
+  echo $MARKDOWN_FILE
+  title_markdown_file $MARKDOWN_FILE
+done
+set -x
+
+# Copy in special files that GitHub wants in the project root.
+cat README.md | grep -v 'project website' > docs/index.md
+cp CHANGELOG.md docs/changelogs/changelog.md
+cp CONTRIBUTING.md docs/contribute/contributing.md
+
+# Build the site locally
+mkdocs build