Use HTML for docs (#7548)

build.gradle.kts

@@ -32,6 +32,8 @@ buildscript {
   }
 }
 
+apply(plugin = "org.jetbrains.dokka")
+
 allprojects {
   group = "com.squareup.okhttp3"
   version = "5.0.0-SNAPSHOT"

deploy_website.sh

@@ -24,39 +24,9 @@ git clone $REPO $DIR
 cd $DIR
 
 # 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
+./gradlew dokkaHtmlMultiModule
 
-# mkdocs doesn't correctly handle the .md paths in package-list, so post-process.
-# See https://github.com/square/okhttp/issues/7338
-find docs/4.x -name package-list -exec sed -i '' -e 's/index.md$/index.html/' -e 's/\.md$/\.html/' -e '1 s/gfm/html/' -e '2 s/md/html/' {} \;
-
-# 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
+mv ./build/dokka/htmlMultiModule docs/4.x
 
 # Copy in special files that GitHub wants in the project root.
 cat README.md | grep -v 'project website' > docs/index.md

docs/features/https.md

@@ -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](../features/tls_configuration_history.md).
+configuration history is [tracked here](../security/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

gradle.properties

@@ -3,3 +3,4 @@ org.gradle.jvmargs='-Dfile.encoding=UTF-8'
 org.gradle.parallel=true
 android.enableJetifier=true
 android.useAndroidX=true
+kotlin.mpp.stability.nowarn=true

gradle/libs.versions.toml

@@ -37,7 +37,7 @@ gradlePlugin-androidJunit5 = "de.mannodermaus.gradle.plugins:android-junit5:1.8.
 gradlePlugin-animalsniffer = "ru.vyarus:gradle-animalsniffer-plugin:1.6.0"
 gradlePlugin-binaryCompatibilityValidator = "org.jetbrains.kotlinx.binary-compatibility-validator:org.jetbrains.kotlinx.binary-compatibility-validator.gradle.plugin:0.12.1"
 gradlePlugin-bnd = { module = "biz.aQute.bnd:biz.aQute.bnd.gradle", version.ref = "biz-aQute-bnd" }
-gradlePlugin-dokka = "org.jetbrains.dokka:dokka-gradle-plugin:1.7.10"
+gradlePlugin-dokka = "org.jetbrains.dokka:dokka-gradle-plugin:1.7.20"
 gradlePlugin-errorprone = "net.ltgt.gradle:gradle-errorprone-plugin:3.0.1"
 gradlePlugin-graal = "com.palantir.graal:gradle-graal:0.12.0"
 gradlePlugin-kotlin = { module = "org.jetbrains.kotlin:kotlin-gradle-plugin", version.ref = "org-jetbrains-kotlin" }

mkdocs.yml

@@ -95,21 +95,22 @@ nav:
     - 'Events': features/events.md
     - 'HTTPS': features/https.md
     - 'Interceptors': features/interceptors.md
+    - 'R8/Proguard': features/r8_proguard.md
   - 'Recipes': recipes.md
   - 'Security':
     - 'Security': security/security.md
     - 'Providers': security/security_providers.md
     - 'Configuration History': security/tls_configuration_history.md
   - 'Works with OkHttp': works_with_okhttp.md
   - 'API':
-    - 'okhttp': 4.x/okhttp/okhttp3/index.md
-    - 'brotli': 4.x/okhttp-brotli/okhttp3.brotli/index.md
-    - 'dnsoverhttps': 4.x/okhttp-dnsoverhttps/okhttp3.dnsoverhttps/index.md
-    - 'logging-interceptor': 4.x/logging-interceptor/okhttp3.logging/index.md
-    - 'sse': 4.x/okhttp-sse/okhttp3.sse/index.md
-    - 'tls': 4.x/okhttp-tls/okhttp3.tls/index.md
-    - 'urlconnection': 4.x/okhttp-urlconnection/okhttp3/index.md
-    - 'mockwebserver': 4.x/mockwebserver/okhttp3.mockwebserver/index.md
+    - 'okhttp': 4.x/okhttp/okhttp3/index.html
+    - 'brotli': 4.x/okhttp-brotli/okhttp3.brotli/index.html
+    - 'dnsoverhttps': 4.x/okhttp-dnsoverhttps/okhttp3.dnsoverhttps/index.html
+    - 'logging-interceptor': 4.x/logging-interceptor/okhttp3.logging/index.html
+    - 'sse': 4.x/okhttp-sse/okhttp3.sse/index.html
+    - 'tls': 4.x/okhttp-tls/okhttp3.tls/index.html
+    - 'urlconnection': 4.x/okhttp-urlconnection/okhttp3/index.html
+    - 'mockwebserver': 4.x/mockwebserver/okhttp3.mockwebserver/index.html
   - 'Change Logs':
     - 'Change Log': changelogs/changelog.md
     - '4.x Change Log': changelogs/changelog_4x.md

test_docs.sh

@@ -9,35 +9,9 @@
 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
+./gradlew dokkaHtmlMultiModule
 
-# 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
+mv ./build/dokka/htmlMultiModule docs/4.x
 
 # Copy in special files that GitHub wants in the project root.
 cat README.md | grep -v 'project website' > docs/index.md