Improve OkHttp Docs (#6566)

* Improve OkHttp documentation

* Remove placeholder files

* remove site folder

* Create upgrading_to_okhttp_4.md

* Add redirects and fix paths

* add missing tls page to redirects

* Use custom SVG icons

* Update deploy_website.sh

* Push new changes.

deploy_website.sh

@@ -53,8 +53,8 @@ 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/changelog.md
-cp CONTRIBUTING.md docs/contributing.md
+cp CHANGELOG.md docs/changelogs/changelog.md
+cp CONTRIBUTING.md docs/contribute/contributing.md
 
 # Build the site and push the new files up to GitHub
 mkdocs gh-deploy

docs/4.x/upgrading_to_okhttp_4.md

@@ -217,7 +217,7 @@ Android Studio’s Advanced Profiling feature rewrites OkHttp bytecode for instr
 Unfortunately it crashes on OkHttp 4.x’s bytecode. Until [Google’s bug][advanced_profiling_bug] is
 fixed you must disable advanced profiling in Android Studio.
 
-![Disable Advanced Profiling](images/disable_advanced_profiling@2x.png)
+![Disable Advanced Profiling](../assets/images/disable_advanced_profiling@2x.png)
 
 
 R8 / ProGuard

docs/assets/css/app.css

@@ -0,0 +1,61 @@
+:root {
+  --external-link-icon: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 512 512'%3E%3Clink xmlns='' type='text/css' rel='stylesheet' id='dark-mode-custom-link'/%3E%3Clink xmlns='' type='text/css' rel='stylesheet' id='dark-mode-general-link'/%3E%3Cstyle xmlns='' lang='en' type='text/css' id='dark-mode-custom-style'/%3E%3Cstyle xmlns='' lang='en' type='text/css' id='dark-mode-native-style'/%3E%3Cpath d='M432 320h-32a16 16 0 0 0-16 16v112H64V128h144a16 16 0 0 0 16-16V80a16 16 0 0 0-16-16H48a48 48 0 0 0-48 48v352a48 48 0 0 0 48 48h352a48 48 0 0 0 48-48V336a16 16 0 0 0-16-16zM488 0H360c-21.37 0-32.05 25.91-17 41l35.73 35.73L135 320.37a24 24 0 0 0 0 34L157.67 377a24 24 0 0 0 34 0l243.61-243.68L471 169c15 15 41 4.5 41-17V24a24 24 0 0 0-24-24z'/%3E%3C/svg%3E");
+}
+
+@font-face {
+    font-family: cash-market;
+    src: url("https://cash-f.squarecdn.com/static/fonts/cash-market/v2/CashMarket-Regular.woff2") format("woff2");
+    font-weight: 400;
+    font-style: normal
+}
+
+@font-face {
+    font-family: cash-market;
+    src: url("https://cash-f.squarecdn.com/static/fonts/cash-market/v2/CashMarket-Medium.woff2") format("woff2");
+    font-weight: 500;
+    font-style: normal
+}
+
+@font-face {
+    font-family: cash-market;
+    src: url("https://cash-f.squarecdn.com/static/fonts/cash-market/v2/CashMarket-Bold.woff2") format("woff2");
+    font-weight: 700;
+    font-style: normal
+}
+
+body, input {
+    font-family: cash-market,"Helvetica Neue",helvetica,sans-serif;
+}
+
+.md-typeset h1, .md-typeset h2, .md-typeset h3, .md-typeset h4 {
+    font-family: cash-market,"Helvetica Neue",helvetica,sans-serif;
+    line-height: normal;
+    font-weight: bold;
+}
+
+button.dl {
+  font-weight: 300;
+  font-size: 25px;
+  line-height: 40px;
+  padding: 3px 10px;
+  display: inline-block;
+  border-radius: 6px;
+  color: #f0f0f0;
+  margin: 5px 0;
+  width: auto;
+}
+
+.logo {
+  text-align: center;
+  margin-top: 150px;
+}
+
+a[href^="http" ]:not(.md-social__link, .md-button, [data-sub-html], .md-footer-social__link, .md-source, .md-search-result__link, .md-logo, [href*="squidfunk.github.io"]):after {
+    background: transparent var(--external-link-icon) 0 0 no-repeat;
+    content: "";
+    display: inline-block;
+    height: 12px;
+    margin-left: 3px;
+    width: 12px;
+    filter: invert(1);
+}

docs/css/app.css

@@ -1,48 +0,0 @@
-@font-face {
-    font-family: cash-market;
-    src: url("https://cash-f.squarecdn.com/static/fonts/cash-market/v2/CashMarket-Regular.woff2") format("woff2");
-    font-weight: 400;
-    font-style: normal
-}
-
-@font-face {
-    font-family: cash-market;
-    src: url("https://cash-f.squarecdn.com/static/fonts/cash-market/v2/CashMarket-Medium.woff2") format("woff2");
-    font-weight: 500;
-    font-style: normal
-}
-
-@font-face {
-    font-family: cash-market;
-    src: url("https://cash-f.squarecdn.com/static/fonts/cash-market/v2/CashMarket-Bold.woff2") format("woff2");
-    font-weight: 700;
-    font-style: normal
-}
-
-body, input {
-    font-family: cash-market,"Helvetica Neue",helvetica,sans-serif;
-}
-
-.md-typeset h1, .md-typeset h2, .md-typeset h3, .md-typeset h4 {
-    font-family: cash-market,"Helvetica Neue",helvetica,sans-serif;
-    line-height: normal;
-    font-weight: bold;
-    color: #353535;
-}
-
-button.dl {
-  font-weight: 300;
-  font-size: 25px;
-  line-height: 40px;
-  padding: 3px 10px;
-  display: inline-block;
-  border-radius: 6px;
-  color: #f0f0f0;
-  margin: 5px 0;
-  width: auto;
-}
-
-.logo {
-  text-align: center;
-  margin-top: 150px;
-}

docs/features/caching.md

@@ -70,7 +70,7 @@ The cache directory must be exclusively owned by a single instance.
 Deleting the cache when it is no longer needed can be done.  However this may delete the purpose of the cache
 which is designed to persist between app restarts.
 
-```
+```kotlin
 cache.delete()
 ```
  
@@ -78,14 +78,14 @@ cache.delete()
 
 Pruning the entire Cache to clear space temporarily can be done using evictAll.
 
-```
+```kotlin
 cache.evictAll()
 ```
 
 Removing individual items can be done using the urls iterator.
 This would be typical after a user initiates a force refresh by a pull to refresh type action.
 
-```
+```java
     val urlIterator = cache.urls()
     while (urlIterator.hasNext()) {
       if (urlIterator.next().startsWith("https://www.google.com/")) {

docs/features/events.md

@@ -10,7 +10,7 @@ Events allow you to capture metrics on your application’s HTTP calls. Use even
 
 Subclass [EventListener](https://square.github.io/okhttp/3.x/okhttp/okhttp3/EventListener.html) and override methods for the events you are interested in. In a successful HTTP call with no redirects or retries the sequence of events is described by this flow.
 
-![Events Diagram](images/events@2x.png)
+![Events Diagram](../assets/images/events@2x.png)
 
 Here’s a [sample event listener](https://github.com/square/okhttp/blob/master/samples/guide/src/main/java/okhttp3/recipes/PrintEventsNonConcurrent.java) that prints each event with a timestamp.
 
@@ -224,7 +224,7 @@ class MetricsEventListener extends EventListener {
 
 When an operation fails, a failure method is called. This is `connectFailed()` for failures while building a connection to the server, and `callFailed()` when the HTTP call fails permanently. When a failure happens it is possible that a `start` event won’t have a corresponding `end` event.
 
-![Events Diagram](images/events_with_failures@2x.png)
+![Events Diagram](../assets/images/events_with_failures@2x.png)
 
 ### Events with Retries and Follow-Ups
 
@@ -232,7 +232,7 @@ OkHttp is resilient and can automatically recover from some connectivity failure
 
 A single HTTP call may require follow-up requests to be made to handle authentication challenges, redirects, and HTTP-layer timeouts. In such cases multiple connections, requests, and responses may be attempted. Follow-ups are another reason a single call may trigger multiple events of the same type.
 
-![Events Diagram](images/events_with_failures_and_retries@2x.png)
+![Events Diagram](../assets/images/events_with_failures_and_retries@2x.png)
 
 ### Availability
 

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](../changelogs/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](../changelogs/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
@@ -70,7 +70,7 @@ By default, OkHttp trusts the certificate authorities of the host platform. This
 
 Use [CertificatePinner](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-certificate-pinner/) to restrict which certificates and certificate authorities are trusted. Certificate pinning increases security, but limits your server team’s abilities to update their TLS certificates. **Do not use certificate pinning without the blessing of your server’s TLS administrator!**
 
-=== "Kotlin"
+=== ":material-language-kotlin: Kotlin"
     ```kotlin
       private val client = OkHttpClient.Builder()
           .certificatePinner(
@@ -93,7 +93,7 @@ Use [CertificatePinner](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-cert
         }
       }
     ```
-=== "Java"
+=== ":material-language-java: Java"
     ```java
       private final OkHttpClient client = new OkHttpClient.Builder()
           .certificatePinner(
@@ -121,7 +121,7 @@ Use [CertificatePinner](https://square.github.io/okhttp/4.x/okhttp/okhttp3/-cert
 
 The full code sample shows how to replace the host platform’s certificate authorities with your own set. As above, **do not use custom certificates without the blessing of your server’s TLS administrator!**
 
-=== "Kotlin"
+=== ":material-language-kotlin: Kotlin"
     ```kotlin
       private val client: OkHttpClient
     
@@ -165,7 +165,7 @@ The full code sample shows how to replace the host platform’s certificate auth
         ... // Full source omitted. See sample.
       }
     ```
-=== "Java"
+=== ":material-language-java: Java"
     ```java
       private final OkHttpClient client;
     

docs/features/interceptors.md

@@ -27,7 +27,7 @@ A call to `chain.proceed(request)` is a critical part of each interceptor’s im
 
 Interceptors can be chained. Suppose you have both a compressing interceptor and a checksumming interceptor: you'll need to decide whether data is compressed and then checksummed, or checksummed and then compressed. OkHttp uses lists to track interceptors, and interceptors are called in order.
 
-![Interceptors Diagram](images/interceptors@2x.png)
+![Interceptors Diagram](../assets/images/interceptors@2x.png)
 
 ### Application Interceptors
 

mkdocs.yml

@@ -7,53 +7,104 @@ site_author: Square, Inc.
 remote_branch: gh-pages
 edit_uri: ""
 
-copyright: 'Copyright © 2019 Square, Inc.'
+copyright: 'Copyright © 2019-2022 Square, Inc.'
 
 theme:
   name: 'material'
-  favicon: images/icon-square.png
-  logo: images/icon-square.png
+  favicon: assets/images/icon-square.png
+  logo: assets/images/icon-square.png
   palette:
-    primary: 'teal'
-    accent: 'white'
+    - media: "(prefers-color-scheme: light)"
+      scheme: default
+      primary: teal
+      accent: blue
+      toggle:
+        icon: octicons/sun-24
+        name: "Switch to Dark Mode"
+    - media: "(prefers-color-scheme: dark)"
+      scheme: slate
+      primary: teal
+      accent: blue
+      toggle:
+        icon: octicons/moon-24
+        name: "Switch to Light Mode"
+  features:
+  - navigation.tabs
 
 extra_css:
-  - 'css/app.css'
+  - 'assets/css/app.css'
 
 markdown_extensions:
   - smarty
-  - codehilite:
-      guess_lang: false
   - footnotes
   - meta
   - toc:
       permalink: true
+  - attr_list
   - pymdownx.betterem:
       smart_enable: all
   - pymdownx.caret
+  - pymdownx.emoji:
+      emoji_index: !!python/name:materialx.emoji.twemoji
+      emoji_generator: !!python/name:materialx.emoji.to_svg
   - pymdownx.inlinehilite
   - pymdownx.magiclink
   - pymdownx.smartsymbols
   - pymdownx.superfences
   - pymdownx.tilde
-  - pymdownx.tabbed
+  - pymdownx.tabbed:
+      alternate_style: true
   - tables
 
+plugins:
+  - redirects:
+      redirect_maps:
+        # Redirect all feature pages to features/*
+        'caching.md': 'features/caching.md'
+        'calls.md': 'features/calls.md'
+        'concurrency.md': 'features/concurrency.md'
+        'connections.md': 'features/connections.md'
+        'debug_logging.md': 'features/debug_logging.md'
+        'events.md': 'features/events.md'
+        'https.md': 'features/events.md'
+        'interceptors.md': 'features/interceptors.md'
+        'r8_proguard.md': 'features/r8_proguard.md'
+        # Redirect all Security pages to security/*
+        'security.md': 'security/security.md'
+        'security_providers.md': 'security/security_providers.md'
+        # Redirect upgrading_to_okhttp_4 to 4.x/*
+        'upgrading_to_okhttp_4.md': '4.x/upgrading_to_okhttp_4.md'
+        # Redirect all changelog pages to changelog/*
+        'changelog.md': 'changelogs/changelog.md'
+        'changelog_3x.md': 'changelogs/changelog_3x.md'
+        'changelog_2x.md': 'changelogs/changelog_2x.md'
+        'changelog_1x.md': 'changelogs/changelog_1x.md'
+        'tls_configuration_history.md': 'changelogs/tls_configuration_history.md'
+        # Redirect all contributing pages to contribute/*
+        'contributing.md': 'contribute/contributing.md'
+        'code_of_conduct.md': 'contribute/code_of_conduct.md'
+
 nav:
-  - 'Overview': index.md
-  - 'Stack Overflow ⏏': https://stackoverflow.com/questions/tagged/okhttp?sort=active
-  - 'Calls': calls.md
-  - 'Caching': caching.md
-  - 'Connections': connections.md
-  - 'Events': events.md
-  - 'HTTPS': https.md
-  - 'Interceptors': interceptors.md
+  - 'Overview':
+    - 'Introduction': index.md
+    - 'Stack Overflow': https://stackoverflow.com/questions/tagged/okhttp?sort=active
+  - 'Features':
+    - 'Caching': features/caching.md
+    - 'Calls': features/calls.md
+    - 'Concurrency': features/concurrency.md
+    - 'Connections': features/connections.md
+    - 'Debug Logging': features/debug_logging.md
+    - 'Events': features/events.md
+    - 'HTTPS': features/https.md
+    - 'Interceptors': features/interceptors.md
+    - 'R8 / ProGuard': features/r8_proguard.md
   - 'Recipes': recipes.md
-  - 'Security': security.md
-  - 'Security Providers': security_providers.md
+  - 'Security':
+    - 'Security Policy': security/security.md
+    - 'Security Providers': security/security_providers.md
   - 'Works with OkHttp': works_with_okhttp.md
-  - 'Upgrading to OkHttp 4': upgrading_to_okhttp_4.md
   - '4.x API':
+    - 'Upgrading to OkHttp 4': 4.x/upgrading_to_okhttp_4.md
     - '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
@@ -63,14 +114,20 @@ nav:
     - 'urlconnection': 4.x/okhttp-urlconnection/okhttp3/index.md
     - 'mockwebserver': 4.x/mockwebserver/okhttp3.mockwebserver/index.md
   - '3.12.x API':
-    - 'okhttp ⏏': https://square.github.io/okhttp/3.x/okhttp/
-    - 'dnsoverhttps ⏏': https://square.github.io/okhttp/3.x/okhttp-dnsoverhttps/
-    - 'logging-interceptor ⏏': https://square.github.io/okhttp/3.x/logging-interceptor/
-    - 'sse ⏏': https://square.github.io/okhttp/3.x/okhttp-sse/
-    - 'tls ⏏': https://square.github.io/okhttp/3.x/okhttp-tls/
-    - 'urlconnection ⏏': https://square.github.io/okhttp/3.x/okhttp-urlconnection/
-    - 'mockwebserver ⏏': https://square.github.io/okhttp/3.x/mockwebserver/
-  - 'Change Log': changelog.md
-  - 'Contributing': contributing.md
-  - 'Code of Conduct': code_of_conduct.md
+    - 'okhttp': https://square.github.io/okhttp/3.x/okhttp/
+    - 'dnsoverhttps': https://square.github.io/okhttp/3.x/okhttp-dnsoverhttps/
+    - 'logging-interceptor': https://square.github.io/okhttp/3.x/logging-interceptor/
+    - 'sse': https://square.github.io/okhttp/3.x/okhttp-sse/
+    - 'tls': https://square.github.io/okhttp/3.x/okhttp-tls/
+    - 'urlconnection': https://square.github.io/okhttp/3.x/okhttp-urlconnection/
+    - 'mockwebserver': https://square.github.io/okhttp/3.x/mockwebserver/
+  - 'Change Logs':
+    - 'Latest': changelogs/changelog.md
+    - 'Version 3.x': changelogs/changelog_3x.md
+    - 'Version 2.x': changelogs/changelog_2x.md
+    - 'Version 1.x': changelogs/changelog_1x.md
+    - 'TLS History': changelogs/tls_configuration_history.md
+  - 'Contributing':
+    - 'Contribute': contribute/contributing.md
+    - 'Code of Conduct': contribute/code_of_conduct.md