Rework docs structure (#2308)

docs/exceptions.md

@@ -1,56 +1,8 @@
 # Exceptions
 
-## Request and Response exceptions
+This page lists exceptions that may be raised when using HTTPX.
 
-The most important exception classes in HTTPX are `RequestError` and `HTTPStatusError`.
-
-The `RequestError` class is a superclass that encompasses any exception that occurs
-while issuing an HTTP request. These exceptions include a `.request` attribute.
-
-```python
-try:
-    response = httpx.get("https://www.example.com/")
-except httpx.RequestError as exc:
-    print(f"An error occurred while requesting {exc.request.url!r}.")
-```
-
-The `HTTPStatusError` class is raised by `response.raise_for_status()` on responses which are not a 2xx success code.
-These exceptions include both a `.request` and a `.response` attribute.
-
-```python
-response = httpx.get("https://www.example.com/")
-try:
-    response.raise_for_status()
-except httpx.HTTPStatusError as exc:
-    print(f"Error response {exc.response.status_code} while requesting {exc.request.url!r}.")
-```
-
-There is also a base class `HTTPError` that includes both of these categories, and can be used
-to catch either failed requests, or 4xx and 5xx responses.
-
-You can either use this base class to catch both categories...
-
-```python
-try:
-    response = httpx.get("https://www.example.com/")
-    response.raise_for_status()
-except httpx.HTTPError as exc:
-    print(f"Error while requesting {exc.request.url!r}.")
-```
-
-Or handle each case explicitly...
-
-```python
-try:
-    response = httpx.get("https://www.example.com/")
-    response.raise_for_status()
-except httpx.RequestError as exc:
-    print(f"An error occurred while requesting {exc.request.url!r}.")
-except httpx.HTTPStatusError as exc:
-    print(f"Error response {exc.response.status_code} while requesting {exc.request.url!r}.")
-```
-
----
+For an overview of how to work with HTTPX exceptions, see [Exceptions (Quickstart)](quickstart.md#exceptions).
 
 ## The exception hierarchy
 

docs/quickstart.md

@@ -479,3 +479,57 @@ as above:
 >>> httpx.get("https://example.com", auth=auth)
 <Response [200 OK]>
 ```
+
+## Exceptions
+
+HTTPX will raise exceptions if an error occurs.
+
+The most important exception classes in HTTPX are `RequestError` and `HTTPStatusError`.
+
+The `RequestError` class is a superclass that encompasses any exception that occurs
+while issuing an HTTP request. These exceptions include a `.request` attribute.
+
+```python
+try:
+    response = httpx.get("https://www.example.com/")
+except httpx.RequestError as exc:
+    print(f"An error occurred while requesting {exc.request.url!r}.")
+```
+
+The `HTTPStatusError` class is raised by `response.raise_for_status()` on responses which are not a 2xx success code.
+These exceptions include both a `.request` and a `.response` attribute.
+
+```python
+response = httpx.get("https://www.example.com/")
+try:
+    response.raise_for_status()
+except httpx.HTTPStatusError as exc:
+    print(f"Error response {exc.response.status_code} while requesting {exc.request.url!r}.")
+```
+
+There is also a base class `HTTPError` that includes both of these categories, and can be used
+to catch either failed requests, or 4xx and 5xx responses.
+
+You can either use this base class to catch both categories...
+
+```python
+try:
+    response = httpx.get("https://www.example.com/")
+    response.raise_for_status()
+except httpx.HTTPError as exc:
+    print(f"Error while requesting {exc.request.url!r}.")
+```
+
+Or handle each case explicitly...
+
+```python
+try:
+    response = httpx.get("https://www.example.com/")
+    response.raise_for_status()
+except httpx.RequestError as exc:
+    print(f"An error occurred while requesting {exc.request.url!r}.")
+except httpx.HTTPStatusError as exc:
+    print(f"Error response {exc.response.status_code} while requesting {exc.request.url!r}.")
+```
+
+For a full list of available exceptions, see [Exceptions (API Reference)](exceptions.md).

mkdocs.yml

@@ -4,6 +4,8 @@ site_url: https://www.python-httpx.org/
 
 theme:
     name: 'material'
+    features:
+        - navigation.sections
 
 repo_name: encode/httpx
 repo_url: https://github.com/encode/httpx/
@@ -11,18 +13,22 @@ edit_uri: ""
 
 nav:
     - Introduction: 'index.md'
-    - QuickStart: 'quickstart.md'
-    - Advanced Usage: 'advanced.md'
-    - Async Support: 'async.md'
-    - HTTP/2 Support: 'http2.md'
-    - Environment Variables: 'environment_variables.md'
-    - Requests Compatibility: 'compatibility.md'
-    - Developer Interface: 'api.md'
-    - Exceptions: 'exceptions.md'
-    - Troubleshooting: 'troubleshooting.md'
-    - Third Party Packages: 'third_party_packages.md'
-    - Contributing: 'contributing.md'
-    - Code of Conduct: 'code_of_conduct.md'
+    - Usage:
+        - QuickStart: 'quickstart.md'
+        - Advanced Usage: 'advanced.md'
+    - Guides:
+        - Async Support: 'async.md'
+        - HTTP/2 Support: 'http2.md'
+        - Requests Compatibility: 'compatibility.md'
+        - Troubleshooting: 'troubleshooting.md'
+    - API Reference:
+        - Developer Interface: 'api.md'
+        - Exceptions: 'exceptions.md'
+        - Environment Variables: 'environment_variables.md'
+    - Community:
+        - Third Party Packages: 'third_party_packages.md'
+        - Contributing: 'contributing.md'
+        - Code of Conduct: 'code_of_conduct.md'
 
 markdown_extensions:
   - admonition