[Proposal] Improve OkHttp Documentation

[Andre601]

This issue serves as a first step in proposing changes to the OkHttp Documentation found under https://square.github.io/okhttp

The reasons

While the docs do look nice do they miss out on a lot of different features that are provided by the 'Material for MkDocs' Theme (Which I call just 'Material' throughout this issue for simplicity reasons) and PyMdown Extensions (Also known as Pymdownx).

Changes

I propose the following main changes to the documentation.

Dark theme

Material offers a simple setting for using dark theme called slate:

theme:
  palette:
    scheme: slate

And let's be honest: This bright theme is not good for the eyes to look at and a dark theme would be a lot better to use.

Note, that the dark theme was addes in a later 5.x version of Material, so upgrading should be recommended.

Using tabs

Material offers the usage of tabs.
This allows you to keep pages organized in tabs, which are visible at the top of the page.

Adding it only requires this in the mkdocs.yml

theme:
  features:
  - navigation.tabs

As mentioned allows this to group pages together under a single name, which makes it look better in comparison to just having all pages listed on the side.

As an example can you group and add the changelog_3x.md, changelog_2x.md, changelog_1x.md and changelog.md under the Change Log section like this:

nav:
# ...
- 'Change Logs': # I suggest renaming this to Change Logs
  - 'Latest': changelog.md
  - 'Version 3.x': changelog_3x.md
  - 'Version 2.x': changelog_2x.md
  - 'Version 1.x': changelog_1x.md

General reordering of pages

Next proposal is to reorder and group pages together into their own separate sections.
You already have 4.x as a separate group, which considering all other pages being separated seems somewhat odd and inconsistent.

I propose the following Folder structure to use:

docs/
  │
  ├─ 4.x/
  │  ├─ mockwebserver/
  │  │  └─ okhttp3.mockwebserver/
  │  │     └─ index.md
  │  ├─ okhttp/
  │  │  └─ okhttp3/
  │  │     └─ index.md
  │  ├─ okhttp-brotli/
  │  │  └─ okhttp3.brotli/
  │  │     └─ index.md
  │  ├─ okhttp-dnsoverhttps/
  │  │  └─ okhttp3.dnsoverhttps/
  │  │     └─ index.md
  │  ├─ okhttp-logging-interceptor/
  │  │  └─ okhttp3.logging/
  │  │     └─ index.md
  │  ├─ okhttp-sse/
  │  │  └─ okhttp3.sse/
  │  │     └─ index.md
  │  ├─ okhttp-tls/
  │  │  └─ okhttp3.tls/
  │  │     └─ index.md
  │  ├─ okhttp-urlconnection/
  │  │  └─ okhttp3/
  │  │     └─ index.md
  │  └─ upgrading_to_okhttp_4.md
  ├─ changelogs/
  │  ├─ changelog.md
  │  ├─ changelog_3x.md
  │  ├─ changelog_2x.md
  │  ├─ changelog_1.md
  │  └─ tls_configuration_history.md
  ├─ contribute/
  │  ├─ code_of_conduct.md
  │  └─ contributing.md
  ├─ features/
  │  ├─ caching.md
  │  ├─ calls.md
  │  ├─ concurrency.md
  │  ├─ connections.md
  │  ├─ debug_logging.md
  │  ├─ events.md
  │  ├─ https.md
  │  ├─ inteceptors.md
  │  └─ r8_proguard.md
  ├─ security/
  │  ├─ security.md
  │  └─ security_providers.md
  ├─ index.md
  ├─ recipes.md
  ├─ releasing.md
  └─ works_with_okhttp.md

The benefits of such a structure would be a more organized look and feel.
Note that this folder structure would also be mostly mirrored in the navigation as follows:

nav:
nav:
  - '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 Policy': security/security.md
    - 'Security Providers': security/security_providers.md
  - 'Works with OkHttp': works_with_okhttp.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
    - 'logging-interceptor': 4.x/okhttp-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
  - '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 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

Usage of other pymdownx extensions

I believe using the Emojis extension of pymdownx together with the MaterialX emoji option, which is part of Material and enables the usage of SVG icons from Fontawesome, Material Design and Octicons, would be beneficial for the documentation.

Right now is the main benefit/feature I imagined, which is displaying something like Fontawesome's external-link-alt icon in the navigation tree on the left, not supported.

I opened an issue on Material proposing such a change, as it would look better to use such an icon to indicate external pages, rather than using ⏏.
Unfortunately is this not doable for extensions and themes.

But perhaps there would also be other places where the usage of either emojis or icons could be beneficial to use.

Live Preview

All the changes I discussed above can be found on a live-preview I made over here: https://andre601.ch/okhttp

Notes

I used the following things for this:

• MkDocs 1.1
• Material for MkDocs 6.2.8
• pymdown-extensions 7.x
• mkdocs-redirects 1.0.1

I used pip install -U mkdocs-material to upgrade Material and all its dependencies and pip install mkdocs-redirects to download the redirects plugin used.

Another note:
With exception of a placeholder index file for the main page do some other pages not exist due to the nature of OkHttp's Documentation structure.

[swankjesse]

Wow, that live preview is amazing. Lets do it.