docs: Improve advanced section

docs/advanced/base-url.md

@@ -0,0 +1,2 @@
+### Define a base URL for all your endpoints only once
+...using `BaseUrlSession` from [requests_toolbelt](https://toolbelt.readthedocs.io/) package

docs/advanced/data-parsers.md

@@ -0,0 +1,25 @@
+# Create your own data parser
+
+To convert your payloads and responses to your favourite format. A typical use case for this could be to deserialize
+responses as python classes. It may be a good place to convert from snake case and camelCase (and viceversa).
+
+In this library we have a basic example using NamedTuples: `NamedTupleParser`.
+
+```python
+from api_client_framework.protocols import Parser
+from typing import Type, NamedTuple, Any
+
+
+class NamedTupleParser(Parser):
+    def __init__(self, named_tuple_class: Type[NamedTuple]):
+        self.named_tuple_class = named_tuple_class
+
+    def to_dict(self, instance: NamedTuple) -> dict:
+        try:
+            return instance._asdict()
+        except AttributeError:
+            return instance
+
+    def to_class(self, dictionary: dict) -> Any:
+        return self.named_tuple_class(**dictionary)
+```

docs/advanced/exception-handlers.md

@@ -0,0 +1,22 @@
+### Convert HTTP exceptions in your custom exceptions
+
+Usually it's a good idea to hide implementation details between layers. We can convert `requests` exceptions
+to our custom exceptions by creating an `ExceptionHandler`.
+
+```python
+from api_client_framework.protocols import ExceptionHandler
+
+
+class MyCustomPermissionDenied(Exception):
+    ...
+
+
+class CustomExceptionHandler(ExceptionHandler):
+    def handle_exception(self, exception, response):
+        # Convert this specific error to our custom error
+        if exception.status_code == 400 and response.data["error_code"] == "permission_denied":
+            raise MyCustomPermissionDenied()
+
+        # Keep other exceptions untouched
+        raise exception
+```

docs/advanced/index.md → docs/advanced/logging.md

@@ -1,11 +1,4 @@
-### Create your own data parsers
-...using `Parser` protocol.
 
-### Convert HTTP exceptions in your custom exceptions
-...by creating your own `exception_handler`
-
-### Define a base URL for all your endpoints only once
-...using `BaseUrlSession` from [requests_toolbelt](https://toolbelt.readthedocs.io/) package
 
 ### Log responses
 ...by adding [a hook](https://requests.readthedocs.io/en/latest/user/advanced.html#event-hooks) in your `requests.Session` instance
@@ -19,4 +12,4 @@ def print_response(response, *args, **kwargs):
 session = requests.Session()
 session.hooks.setdefault("response", [])
 session.hooks["response"].append(print_response)
-```
+```

mkdocs.yml

@@ -43,4 +43,8 @@ nav:
   - Geting started:
       - 'getting-started/describe-endpoints.md'
       - 'getting-started/create-client.md'
-  - Advanced: 'advanced/index.md'
+  - Advanced:
+      - 'advanced/data-parsers.md'
+      - 'advanced/exception-handlers.md'
+      - 'advanced/base-url.md'
+      - 'advanced/logging.md'