Update README, use more cross-references

README.rst

@@ -68,39 +68,17 @@ To get a client for a given resource, you can use:
 
 .. code-block:: python
 
+    from zgw_consumers.client import build_client
     from zgw_consumers.models import Service
 
-    client = Service.get_client(some_url)
+    my_service = Service.objects.get(api_root="https://api.example.com/")
+    client = build_client(my_service)
 
-Or, to just retrieve the auth header(s):
+    with client:
+        # The preferred way to use the client is within a context manager
+        client.get("relative/url")
 
-.. code-block:: python
-
-    from zgw_consumers.models import Service
-
-    auth = Service.get_auth_header(some_url)
-
-**Data model**
-
-Use ``zgw_consumers.api_models.base.factory`` to turn raw JSON responses into instances
-of domain models:
-
-.. code-block:: python
-
-    from zgw_consumers.api_models.base import factory
-    from zgw_consumers.api_models.zaken import Zaak
-
-    results = client.list("zaak")["results"]
-
-    return factory(Zaak, results)
-
-
-It works for both collections and scalar values, and takes care of the camel-case to
-snake case conversion.
-
-
-You can also define your own data models, take a look at the ``zgw_consumers.api_models``
-package for inspiration.
+The resulting client will have certificate and authentication automatically configured from the database configuration.
 
 .. |build-status| image:: https://github.com/maykinmedia/zgw-consumers/workflows/Run%20CI/badge.svg
     :target: https://github.com/maykinmedia/zgw-consumers/actions?query=workflow%3A%22Run+CI%22

docs/conf.py

@@ -35,6 +35,7 @@
 # ones.
 extensions = [
     "sphinx.ext.autodoc",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.viewcode",
 ]
 
@@ -58,3 +59,11 @@
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = []
+
+# -- Intersphinx configuration -----------------------------------------------
+
+intersphinx_mapping = {
+    "requests": ("https://requests.readthedocs.io/en/latest/", None),
+    "ape-pie": ("https://ape-pie.readthedocs.io/en/latest/", None),
+    "zds-client": ("https://gemma-zds-client.readthedocs.io/en/latest/", None),
+}

docs/index.rst

@@ -34,6 +34,7 @@ can still leverage the utilities offered by ZGW Consumers.
    model_fields
    drf
    testing
+   reference
 
 Indices and tables
 ==================

docs/quickstart.rst

@@ -32,8 +32,8 @@ In the Django admin, you can create:
 Using ``ape-pie`` to interact with your service
 ***********************************************
 
-From a service, you can construct an `APIClient <https://ape-pie.readthedocs.io/en/latest/>`_ instance
-(which is nothing more than an extension to the `requests.Session <https://requests.readthedocs.io/en/latest/user/advanced/#session-objects>`_ object).
+From a service, you can construct an :class:`ape_pie.APIClient` instance
+(which is nothing more than an extension to the :class:`requests.Session` object).
 
 .. code-block:: python
 
@@ -51,11 +51,11 @@ The resulting client will have certificate and authentication automatically conf
 
 .. note::
 
-    By default, ``build_client`` will return an instance of an ``zgw_consumers.nlx.NLXClient``, which will take care of rewriting URLs.
+    By default, :func:`zgw_consumers.client.build_client` will return an instance of an :class:`zgw_consumers.nlx.NLXClient`, which will take care of rewriting URLs.
     You can customize this behavior by using the ``client_factory`` argument.
 
-    If you want to customize how configuration is extracted from the ``Service``, you can
-    make use of the ``zgw_consumers.client.ServiceConfigAdapter`` directly.
+    If you want to customize how configuration is extracted from the :class:`zgw_consumers.models.Service`, you can
+    make use of the :class:`zgw_consumers.client.ServiceConfigAdapter` directly.
 
 
 Constructing an OpenAPI 3 client with the legacy client
@@ -64,7 +64,7 @@ Constructing an OpenAPI 3 client with the legacy client
 .. deprecated:: 0.28.x
     The legacy client is deprecated and will be removed in the next major release.
 
-From a service, you can construct a `client <https://pypi.org/project/gemma-zds-client/>`_
+From a service, you can construct a :class:`zds_client.client.Client`
 instance which is driven by the API schema. There are two common scenario's:
 
 **If you know upfront which service you need to consume**
@@ -96,7 +96,7 @@ client directly based on the URL and the best ``api_root`` match:
 Obtaining the authentication details
 ************************************
 
-Similar to ``Service.get_client``, you can also invoke ``Service.get_auth_header``:
+Similar to :meth:`Service.get_client <zgw_consumers.models.Service.get_client>`, you can also invoke :meth:`Service.get_auth_header <zgw_consumers.models.Service.get_auth_header>`:
 
 .. code-block:: python
 

docs/reference.rst

@@ -0,0 +1,16 @@
+=============
+API reference
+=============
+
+``client``
+==========
+
+.. automodule:: zgw_consumers.client
+    :members:
+
+``nlx``
+=======
+
+.. automodule:: zgw_consumers.nlx
+    :members: NLXClient, get_nlx_services
+    :undoc-members:

docs/settings.rst

@@ -15,13 +15,13 @@ default.
 
 ``ZGW_CONSUMERS_CLIENT_CLASS``
     A dotted python path to the client class to use when building clients from services.
-    This class must implement the interface of ``zds_client.Client``. Defaults to
+    This class must implement the interface of :class:`zds_client.client.Client`. Defaults to
     ``"zgw_consumers.legacy.client.ZGWClient"``. For NLX support, you would override this to
     include the ``zgw_consumers.legacy.nlx.NLXClientMixin``.
 
     .. deprecated:: 0.28.x
        The ``ZGWClient`` is deprecated and will be removed in the next major release. Instead,
-       use the new `ape_pie.APIClient <https://ape-pie.readthedocs.io/en/latest/>`_ or ``zgw_consumers.nlx.NLXClient``.
+       use the new :class:`ape_pie.client.APIClient` or :class:`zgw_consumers.nlx.NLXClient`.
 
 
 ``ZGW_CONSUMERS_TEST_SCHEMA_DIRS``

zgw_consumers/client.py

@@ -32,7 +32,7 @@ def build_client(
 
 @dataclass
 class ServiceConfigAdapter:
-    """An ``ape-pie`` config adapter that will extract session kwargs
+    """An implementation of :class:`ape_pie.ConfigAdapter` that will extract session kwargs
     from a given :class:`zgw_consumers.models.Service`.
     """
 
@@ -73,6 +73,8 @@ def get_client_session_kwargs(self) -> dict[str, Any]:
 
 @dataclass
 class APIKeyAuth(AuthBase):
+    """API Key based :class:`requests.auth.AuthBase` implementation."""
+
     header: str
     key: str
 
@@ -83,6 +85,8 @@ def __call__(self, request: PreparedRequest):
 
 @dataclass
 class ZGWAuth(AuthBase):
+    """:class:`requests.auth.AuthBase` implementation for :class:`zds_client.auth.ClientAuth`."""
+
     service: Service
     auth: ClientAuth = field(init=False)
 

zgw_consumers/nlx.py

@@ -151,6 +151,10 @@ def prepare_request(self, request: Request) -> PreparedRequest:
 
 
 class NLXClient(NLXMixin, APIClient):
+    """A :class:`ape_pie.APIClient` implementation that will take care of rewriting
+    URLs with :external:ref:`an event hook <event-hooks>`.
+    """
+
     pass