Improve OkHttp documentation.

Combine the marketing page (index.md) with the GitHub README.md.

Fix links pointing to 3.x documentation.

Use Markdown tables instead of HTML tables.

.gitignore

@@ -25,3 +25,9 @@ classes
 obj
 
 .DS_Store
+
+# Special Mkdocs files
+docs/api
+docs/changelog.md
+docs/contributing.md
+docs/index.md

CHANGELOG.md

@@ -9,7 +9,7 @@ _2019-06-03_
 bugs or performance regressions before the final 4.0.0 release.
 
 We tried our best to make it fast and safe to upgrade from OkHttp 3.x.
-[We even wrote a guide](docs/upgrading_to_okhttp_4.md) to help you with it!
+[We even wrote a guide][upgrading_to_okhttp_4] to help you with it!
 
 
 ## Version 3.14.2
@@ -1304,7 +1304,7 @@ _2014-12-30_
     running SSLv3, you must manually configure your own `ConnectionSpec`.
 
  *  **OkHttp now offers interceptors.** Interceptors are a powerful mechanism
-    that can monitor, rewrite, and retry calls. The [interceptors doc](docs/interceptors.md) is a full
+    that can monitor, rewrite, and retry calls. The [interceptors doc][interceptors] is a full
     introduction to this new API.
 
  *  New: APIs to iterate and selectively clear the response cache.
@@ -1787,5 +1787,7 @@ Initial release.
  [require_android_5]: https://medium.com/square-corner-blog/okhttp-3-13-requires-android-5-818bb78d07ce
  [obsolete_apache_client]: https://gist.github.com/swankjesse/09721f72039e3a46cf50f94323deb82d
  [obsolete_url_factory]: https://gist.github.com/swankjesse/dd91c0a8854e1559b00f5fc9c7bfae70
- [tls_configuration_history]: docs/tls_configuration_history.md
+ [tls_configuration_history]: http://square.github.io/okhttp/tls_configuration_history/
  [grpc_http2]: https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md
+ [upgrading_to_okhttp_4]: http://square.github.io/okhttp/upgrading_to_okhttp_4/
+ [interceptors]: http://square.github.io/okhttp/interceptors/

CONTRIBUTING.md

@@ -4,16 +4,16 @@ Contributing
 Keeping the project small and stable limits our ability to accept new contributors. We are not
 seeking new committers at this time, but some small contributions are welcome.
 
-If you've found a security problem, please follow our [bug bounty](BUG-BOUNTY.md) program.
+If you've found a security problem, please follow our [bug bounty][security] program.
 
 If you've found a bug, please contribute a failing test case so we can study and fix it.
 
 If you have a new feature idea, please build it in an external library. There are
-[many libraries](./docs/works_with_okhttp.md) that sit on top or hook in via existing APIs. If you build
+[many libraries][works_with_okhttp] that sit on top or hook in via existing APIs. If you build
 something that integrates with OkHttp, tell us so that we can link it!
 
 Before code can be accepted all contributors must complete our
-[Individual Contributor License Agreement (CLA)](https://spreadsheets.google.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1).
+[Individual Contributor License Agreement (CLA)][cla].
 
 
 Code Contributions
@@ -35,5 +35,11 @@ squash all pull requests on merge.
 Committer's Guides
 ------------------
 
- * [Concurrency](./docs/concurrency.md)
- * [Releasing](RELEASING.md)
+ * [Concurrency][concurrency]
+ * [Releasing][releasing]
+
+ [cla]: https://spreadsheets.google.com/spreadsheet/viewform?formkey=dDViT2xzUHAwRkI3X3k5Z0lQM091OGc6MQ&ndplr=1
+ [concurrency]: http://square.github.io/okhttp/concurrency/
+ [releasing]: http://square.github.io/okhttp/releasing/
+ [security]: http://square.github.io/okhttp/security/
+ [works_with_okhttp]: http://square.github.io/okhttp/works_with_okhttp/

README.md

@@ -1,9 +1,72 @@
 OkHttp
 ======
 
-An HTTP & HTTP/2 client for Android and Java applications.
+See the [project website][okhttp] for documentation and APIs.
 
-See the [**project website**][website] for documentation and APIs.
+HTTP is the way modern applications network. It’s how we exchange data & media. Doing HTTP
+efficiently makes your stuff load faster and saves bandwidth.
+
+OkHttp is an HTTP client that’s efficient by default:
+
+ * HTTP/2 support allows all requests to the same host to share a socket.
+ * Connection pooling reduces request latency (if HTTP/2 isn’t available).
+ * Transparent GZIP shrinks download sizes.
+ * Response caching avoids the network completely for repeat requests.
+
+OkHttp perseveres when the network is troublesome: it will silently recover from common connection
+problems. If your service has multiple IP addresses OkHttp will attempt alternate addresses if the
+first connect fails. This is necessary for IPv4+IPv6 and for services hosted in redundant data
+centers. OkHttp supports modern TLS features (TLS 1.3, ALPN, certificate pinning). It can be
+configured to fall back for broad connectivity.
+
+Using OkHttp is easy. Its request/response API is designed with fluent builders and immutability. It
+supports both synchronous blocking calls and async calls with callbacks.
+
+
+Get a URL
+---------
+
+This program downloads a URL and prints its contents as a string. [Full source][get_example].
+
+```java
+OkHttpClient client = new OkHttpClient();
+
+String run(String url) throws IOException {
+  Request request = new Request.Builder()
+      .url(url)
+      .build();
+
+  try (Response response = client.newCall(request).execute()) {
+    return response.body().string();
+  }
+}
+```
+
+
+Post to a Server
+----------------
+
+This program posts data to a service. [Full source][post_example].
+
+```java
+public static final MediaType JSON
+    = MediaType.get("application/json; charset=utf-8");
+
+OkHttpClient client = new OkHttpClient();
+
+String post(String url, String json) throws IOException {
+  RequestBody body = RequestBody.create(JSON, json);
+  Request request = new Request.Builder()
+      .url(url)
+      .post(body)
+      .build();
+  try (Response response = client.newCall(request).execute()) {
+    return response.body().string();
+  }
+}
+```
+
+Further examples are on the [OkHttp Recipes page][recipes].
 
 
 Requirements
@@ -30,10 +93,11 @@ The OkHttp 3.12.x branch supports Android 2.3+ (API level 9+) and Java 7+. These
 support for TLS 1.2 and should not be used. But because upgrading is difficult we will backport
 critical fixes to the [3.12.x branch][okhttp_312x] through December 31, 2020.
 
+
 Releases
 --------
 
-Our [change log](CHANGELOG.md) has release history.
+Our [change log][changelog] has release history.
 
 ```kotlin
 implementation("com.squareup.okhttp3:okhttp:3.14.2")
@@ -42,6 +106,14 @@ implementation("com.squareup.okhttp3:okhttp:3.14.2")
 Snapshot builds are [available][snap].
 
 
+R8 / ProGuard
+-------------
+
+If you are using R8 or ProGuard add the options from [`okhttp3.pro`][okhttp3_pro].
+
+You might also need rules for Okio which is a dependency of this library.
+
+
 MockWebServer
 -------------
 
@@ -51,34 +123,34 @@ OkHttp includes a library for testing HTTP, HTTPS, and HTTP/2 clients.
 testImplementation("com.squareup.okhttp3:mockwebserver:3.14.2")
 ```
 
-R8 / ProGuard
--------------
-
-If you are using R8 or ProGuard add the options from [`okhttp3.pro`][okhttp3_pro].
-
-You might also need rules for Okio which is a dependency of this library.
-
 
 License
 -------
 
-    Licensed under the Apache License, Version 2.0 (the "License");
-    you may not use this file except in compliance with the License.
-    You may obtain a copy of the License at
+```
+Copyright 2019 Square, Inc.
 
-       http://www.apache.org/licenses/LICENSE-2.0
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
 
-    Unless required by applicable law or agreed to in writing, software
-    distributed under the License is distributed on an "AS IS" BASIS,
-    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-    See the License for the specific language governing permissions and
-    limitations under the License.
+   http://www.apache.org/licenses/LICENSE-2.0
 
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+```
 
+ [changelog]: http://square.github.io/okhttp/changelog/
  [conscrypt]: https://github.com/google/conscrypt/
+ [get_example]: https://raw.github.com/square/okhttp/master/samples/guide/src/main/java/okhttp3/guide/GetExample.java
+ [okhttp3_pro]: https://github.com/square/okhttp/blob/master/okhttp/src/main/resources/META-INF/proguard/okhttp3.pro
  [okhttp_312x]: https://github.com/square/okhttp/tree/okhttp_3.12.x
- [okio]: https://github.com/square/okio/
+ [okhttp]: https://square.github.io/okhttp/
+ [okio]: https://github.com/square/okio
+ [post_example]: https://raw.github.com/square/okhttp/master/samples/guide/src/main/java/okhttp3/guide/PostExample.java
+ [recipes]: http://square.github.io/okhttp/recipes/
  [snap]: https://oss.sonatype.org/content/repositories/snapshots/
  [tls_history]: https://square.github.io/okhttp/tls_configuration_history/
- [website]: https://square.github.io/okhttp
- [okhttp3_pro]: https://github.com/square/okhttp/blob/master/okhttp/src/main/resources/META-INF/proguard/okhttp3.pro

deploy_website.sh

@@ -30,6 +30,11 @@ cd $DIR
   :okhttp-urlconnection:dokka \
   :okhttp:dokka
 
+# 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
+
 # Build the site and push the new files up to GitHub
 mkdocs gh-deploy
 

docs/calls.md

@@ -2,11 +2,11 @@
 
 The HTTP client’s job is to accept your request and produce its response. This is simple in theory but it gets tricky in practice.
 
-## [Requests](http://square.github.io/okhttp/3.x/okhttp/okhttp3/Request.html)
+## [Requests](http://square.github.io/okhttp/api/okhttp/okhttp3/-request/)
 
 Each HTTP request contains a URL, a method (like `GET` or `POST`), and a list of headers. Requests may also contain a body: a data stream of a specific content type.
 
-## [Responses](http://square.github.io/okhttp/3.x/okhttp/okhttp3/Response.html)
+## [Responses](http://square.github.io/okhttp/api/okhttp/okhttp3/-response/)
 
 The response answers the request with a code (like 200 for success or 404 for not found), headers, and its own optional body.
 
@@ -28,25 +28,25 @@ If a conditional GET was successful, responses from the network and cache are me
 
 When your requested URL has moved, the webserver will return a response code like `302` to indicate the document’s new URL. OkHttp will follow the redirect to retrieve a final response.
 
-If the response issues an authorization challenge, OkHttp will ask the [`Authenticator`](http://square.github.io/okhttp/3.x/okhttp/okhttp3/Authenticator.html) (if one is configured) to satisfy the challenge. If the authenticator supplies a credential, the request is retried with that credential included.
+If the response issues an authorization challenge, OkHttp will ask the [`Authenticator`](http://square.github.io/okhttp/api/okhttp/okhttp3/-authenticator/) (if one is configured) to satisfy the challenge. If the authenticator supplies a credential, the request is retried with that credential included.
 
 ## Retrying Requests
 
 Sometimes connections fail: either a pooled connection was stale and disconnected, or the webserver itself couldn’t be reached. OkHttp will retry the request with a different route if one is available.
 
-## [Calls](http://square.github.io/okhttp/3.x/okhttp/okhttp3/Call.html)
+## [Calls](http://square.github.io/okhttp/api/okhttp/okhttp3/-call/)
 
 With rewrites, redirects, follow-ups and retries, your simple request may yield many requests and responses. OkHttp uses `Call` to model the task of satisfying your request through however many intermediate requests and responses are necessary. Typically this isn’t many! But it’s comforting to know that your code will continue to work if your URLs are redirected or if you failover to an alternate IP address.
 
 Calls are executed in one of two ways:
 
  * **Synchronous:** your thread blocks until the response is readable.
- * **Asynchronous:** you enqueue the request on any thread, and get [called back](http://square.github.io/okhttp/3.x/okhttp/okhttp3/Callback.html) on another thread when the response is readable.
+ * **Asynchronous:** you enqueue the request on any thread, and get [called back](http://square.github.io/okhttp/api/okhttp/okhttp3/-callback/) on another thread when the response is readable.
 
 Calls can be canceled from any thread. This will fail the call if it hasn’t yet completed! Code that is writing the request body or reading the response body will suffer an `IOException` when its call is canceled.
 
 ## Dispatch
 
 For synchronous calls, you bring your own thread and are responsible for managing how many simultaneous requests you make. Too many simultaneous connections wastes resources; too few harms latency.
 
-For asynchronous calls, [`Dispatcher`](http://square.github.io/okhttp/3.x/okhttp/okhttp3/Dispatcher.html) implements policy for maximum simultaneous requests. You can set maximums per-webserver (default is 5), and overall (default is 64).
+For asynchronous calls, [`Dispatcher`](http://square.github.io/okhttp/api/okhttp/okhttp3/-dispatcher/) implements policy for maximum simultaneous requests. You can set maximums per-webserver (default is 5), and overall (default is 64).

docs/connections.md

@@ -3,7 +3,7 @@ Connections
 
 Although you provide only the URL, OkHttp plans its connection to your webserver using three types: URL, Address, and Route.
 
-#### [URLs](http://square.github.io/okhttp/3.x/okhttp/okhttp3/HttpUrl.html)
+#### [URLs](http://square.github.io/okhttp/api/okhttp/okhttp3/-http-url/)
 
 URLs (like `https://github.com/square/okhttp`) are fundamental to HTTP and the Internet. In addition to being a universal, decentralized naming scheme for everything on the web, they also specify how to access web resources.
 
@@ -14,21 +14,21 @@ URLs are abstract:
 
 They're also concrete: each URL identifies a specific path (like `/square/okhttp`) and query (like `?q=sharks&lang=en`). Each webserver hosts many URLs.
 
-#### [Addresses](http://square.github.io/okhttp/3.x/okhttp/okhttp3/Address.html)
+#### [Addresses](http://square.github.io/okhttp/api/okhttp/okhttp3/-address/)
 
 Addresses specify a webserver (like `github.com`) and all of the **static** configuration necessary to connect to that server: the port number, HTTPS settings, and preferred network protocols (like HTTP/2 or SPDY).
 
-URLs that share the same address may also share the same underlying TCP socket connection. Sharing a connection has substantial performance benefits: lower latency, higher throughput (due to [TCP slow start](http://www.igvita.com/2011/10/20/faster-web-vs-tcp-slow-start/)) and conserved battery. OkHttp uses a [ConnectionPool](http://square.github.io/okhttp/3.x/okhttp/okhttp3/ConnectionPool.html) that automatically reuses HTTP/1.x connections and multiplexes HTTP/2 and SPDY connections.
+URLs that share the same address may also share the same underlying TCP socket connection. Sharing a connection has substantial performance benefits: lower latency, higher throughput (due to [TCP slow start](http://www.igvita.com/2011/10/20/faster-web-vs-tcp-slow-start/)) and conserved battery. OkHttp uses a [ConnectionPool](http://square.github.io/okhttp/api/okhttp/okhttp3/-connection-pool/) that automatically reuses HTTP/1.x connections and multiplexes HTTP/2 and SPDY connections.
 
-In OkHttp some fields of the address come from the URL (scheme, hostname, port) and the rest come from the [OkHttpClient](http://square.github.io/okhttp/3.x/okhttp/okhttp3/OkHttpClient.html).
+In OkHttp some fields of the address come from the URL (scheme, hostname, port) and the rest come from the [OkHttpClient](http://square.github.io/okhttp/api/okhttp/okhttp3/-ok-http-client/).
 
-#### [Routes](http://square.github.io/okhttp/3.x/okhttp/okhttp3/Route.html)
+#### [Routes](http://square.github.io/okhttp/api/okhttp/okhttp3/-route/)
 
 Routes supply the **dynamic** information necessary to actually connect to a webserver. This is the specific IP address to attempt (as discovered by a DNS query), the exact proxy server to use (if a [ProxySelector](http://developer.android.com/reference/java/net/ProxySelector.html) is in use), and which version of TLS to negotiate (for HTTPS connections).
 
 There may be many routes for a single address. For example, a webserver that is hosted in multiple datacenters may yield multiple IP addresses in its DNS response.
 
-#### [Connections](http://square.github.io/okhttp/3.x/okhttp/okhttp3/Connection.html)
+#### [Connections](http://square.github.io/okhttp/api/okhttp/okhttp3/-connection/)
 
 When you request a URL with OkHttp, here's what it does:
 

docs/https.md

@@ -6,9 +6,9 @@ OkHttp attempts to balance two competing concerns:
  * **Connectivity** to as many hosts as possible. That includes advanced hosts that run the latest versions of [boringssl](https://boringssl.googlesource.com/boringssl/) and less out of date hosts running older versions of [OpenSSL](https://www.openssl.org/).
  * **Security** of the connection. This includes verification of the remote webserver with certificates and the privacy of data exchanged with strong ciphers.
 
-When negotiating a connection to an HTTPS server, OkHttp needs to know which [TLS versions](http://square.github.io/okhttp/3.x/okhttp/okhttp3/TlsVersion.html) and [cipher suites](http://square.github.io/okhttp/3.x/okhttp/okhttp3/CipherSuite.html) to offer. A client that wants to maximize connectivity would include obsolete TLS versions and weak-by-design cipher suites. A strict client that wants to maximize security would be limited to only the latest TLS version and strongest cipher suites.
+When negotiating a connection to an HTTPS server, OkHttp needs to know which [TLS versions](http://square.github.io/okhttp/api/okhttp/okhttp3/-tls-version/) and [cipher suites](http://square.github.io/okhttp/api/okhttp/okhttp3/-cipher-suite/) to offer. A client that wants to maximize connectivity would include obsolete TLS versions and weak-by-design cipher suites. A strict client that wants to maximize security would be limited to only the latest TLS version and strongest cipher suites.
 
-Specific security vs. connectivity decisions are implemented by [ConnectionSpec](http://square.github.io/okhttp/3.x/okhttp/okhttp3/ConnectionSpec.html). OkHttp includes four built-in connection specs:
+Specific security vs. connectivity decisions are implemented by [ConnectionSpec](http://square.github.io/okhttp/api/okhttp/okhttp3/-connection-spec/). OkHttp includes four built-in connection specs:
 
  * `RESTRICTED_TLS` is a secure configuration, intended to meet stricter compliance requirements.
  * `MODERN_TLS` is a secure configuration that connects to modern HTTPS servers.
@@ -47,7 +47,7 @@ OkHttpClient client = new OkHttpClient.Builder()
 
 By default, OkHttp trusts the certificate authorities of the host platform. This strategy maximizes connectivity, but it is subject to certificate authority attacks such as the [2011 DigiNotar attack](http://www.computerworld.com/article/2510951/cybercrime-hacking/hackers-spied-on-300-000-iranians-using-fake-google-certificate.html). It also assumes your HTTPS servers’ certificates are signed by a certificate authority.
 
-Use [CertificatePinner](http://square.github.io/okhttp/3.x/okhttp/okhttp3/CertificatePinner.html) 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!**
+Use [CertificatePinner](http://square.github.io/okhttp/api/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!**
 
 ```java
   public CertificatePinning() {