add cmem-client documentation and update task to refresh documentation

.gitignore

@@ -9,3 +9,4 @@ tmp
 .vscode/
 .python-version
 dist/
+.env

.markdownlint.jsonc

@@ -28,14 +28,16 @@
       "span",
       "summary",
       "connection",
-      "tool"
+      "tool",
+      "code"
     ]
   },
   "MD035": false,
   "MD036": false,
   "MD041": false,
   "MD045": false,
   "MD046": false,
+  "MD051": false,
   "MD059": false,
   "MD060": false,
   "MD077": false

Taskfile.yml

@@ -3,6 +3,8 @@
 
 version: '3'
 
+dotenv: ['.env']
+
 vars:
   PUBLIC_BRANCH: published
   CURRENT_VERSION: 26.2
@@ -135,6 +137,39 @@ tasks:
     vars:
       REFERENCE_DIR: docs/automate/cmemc-command-line-interface/command-reference
 
+  update:cmem-client-api:
+    desc: re-generates the cmem-client Python API reference (needs local cmem-client checkout)
+    summary: |
+      Regenerates docs/develop/cmem-client-api/api-reference from the
+      docstrings of a local cmem-client checkout, via that repository's own
+      `task docs:export-md` (see etc/export_api_md.py there).
+
+      The landing page (docs/develop/cmem-client-api/index.md) and its
+      .pages file are hand-written and untouched by this task - only the
+      api-reference/ subtree is wiped and regenerated.
+
+      This documents whatever branch/commit is currently checked out in
+      CMEM_CLIENT_DIR, not necessarily the last release - check out the ref
+      you want documented before running this.
+
+        CMEM_CLIENT_DIR=/path/to/cmem-client task update:cmem-client-api
+    preconditions:
+      - sh: '[ -n "{{.CMEM_CLIENT_DIR}}" ]'
+        msg: |
+          CMEM_CLIENT_DIR is not set. Run this task with the path to a local
+          cmem-client checkout, e.g.:
+
+            CMEM_CLIENT_DIR=/path/to/cmem-client task update:cmem-client-api
+    cmds:
+      - rm -rf {{.REFERENCE_DIR}}/*
+      - task -d {{.CMEM_CLIENT_DIR}} docs:export-md OUTPUT_DIR={{.ROOT_DIR}}/{{.REFERENCE_DIR}}
+      - cmd: >
+          find {{.ROOT_DIR}}/{{.REFERENCE_DIR}} -type f -name '*.md' -print0
+          | xargs -0 poetry run rumdl --config .markdownlint.jsonc check --fix
+        ignore_error: true
+    vars:
+      REFERENCE_DIR: docs/develop/cmem-client-api/api-reference
+
   update:shape-reference:
     desc: re-generates the shape and datatype references (needs local CO)
     summary: >

docs/develop/.pages

@@ -4,6 +4,7 @@ nav:
     - Python Plugins: python-plugins
     - Marketplace Packages: packages
     - cmempy - Python API: cmempy-python-api
+    - cmem-client - Python API: cmem-client-api
     - cmemc - Python Scripts: cmemc-scripts
     - Build (DataIntegration) APIs: dataintegration-apis
     - Explore backend APIs: dataplatform-apis

docs/develop/cmem-client-api/.pages

@@ -0,0 +1,3 @@
+nav:
+    - "cmem-client: Python API": index.md
+    - API Reference: api-reference

docs/develop/cmem-client-api/api-reference/.pages

@@ -0,0 +1,10 @@
+nav:
+    - API Reference: index.md
+    - client: client
+    - config: config
+    - exceptions: exceptions
+    - logging_utils: logging_utils
+    - auth_provider: auth_provider
+    - components: components
+    - models: models
+    - repositories: repositories

docs/develop/cmem-client-api/api-reference/auth_provider/.pages

@@ -0,0 +1,7 @@
+title: auth_provider
+nav:
+    - abc: abc
+    - client_credentials: client_credentials
+    - password: password
+    - prefetched_token: prefetched_token
+    - provided_token: provided_token

docs/develop/cmem-client-api/api-reference/auth_provider/abc/index.md

@@ -0,0 +1,207 @@
+---
+title: "cmem-client: auth_provider.abc module"
+description: "Abstract base class and factory for authentication providers."
+tags:
+  - API
+  - Python
+  - cmem-client
+---
+
+# `cmem_client.auth_provider.abc` {#cmem_client.auth_provider.abc}
+
+<!-- This file was generated - DO NOT CHANGE IT MANUALLY -->
+
+Abstract base class and factory for authentication providers.
+
+This module defines the AuthProvider abstract base class that establishes the
+interface all authentication providers must implement. It also provides a
+factory method that automatically selects the appropriate authentication
+provider based on environment variables.
+
+The factory method supports automatic configuration from environment variables,
+making it easy to switch between different authentication methods without
+code changes by simply setting the OAUTH_GRANT_TYPE environment variable.
+
+**Classes:**
+
+- [**AuthProvider**](#cmem_client.auth_provider.abc.AuthProvider) – Abstract base class for authentication providers.
+
+**Attributes:**
+
+- [**DEFAULT_OAUTH_CLIENT_ID**](#cmem_client.auth_provider.abc.DEFAULT_OAUTH_CLIENT_ID) –
+
+## `AuthProvider` {#cmem_client.auth_provider.abc.AuthProvider}
+
+Bases: <code>ABC</code>
+
+Abstract base class for authentication providers.
+
+AuthProvider defines the common interface that all authentication providers
+must implement to work with the Corporate Memory client. It provides the
+contract for obtaining access tokens and includes a factory method for
+creating appropriate provider instances based on environment configuration.
+
+All concrete authentication provider implementations must inherit from this
+class and implement the get_access_token method. The class also provides
+automatic provider selection through environment variables.
+
+**Functions:**
+
+- [**from_cmempy**](#cmem_client.auth_provider.abc.AuthProvider.from_cmempy) – Create an authentication provider from a cmempy environment.
+- [**from_context**](#cmem_client.auth_provider.abc.AuthProvider.from_context) – Create an authentication provider from a cmem-plugin-base context object.
+- [**from_dict**](#cmem_client.auth_provider.abc.AuthProvider.from_dict) – Create an authentication provider from a plain dictionary.
+- [**from_env**](#cmem_client.auth_provider.abc.AuthProvider.from_env) – Create an authentication provider from environment variables.
+- [**get_access_token**](#cmem_client.auth_provider.abc.AuthProvider.get_access_token) – Get the access token for Bearer Authorization header.
+
+**Attributes:**
+
+- [**logger**](#cmem_client.auth_provider.abc.AuthProvider.logger) (<code>Logger</code>) – The logger for the auth provider.
+- [**preferred_username**](#cmem_client.auth_provider.abc.AuthProvider.preferred_username) (<code>str</code>) – The preferred username for the authentication provider.
+
+### `from_cmempy` {#cmem_client.auth_provider.abc.AuthProvider.from_cmempy}
+
+```python
+from_cmempy(config)
+```
+
+Create an authentication provider from a cmempy environment.
+
+### `from_context` {#cmem_client.auth_provider.abc.AuthProvider.from_context}
+
+```python
+from_context(context)
+```
+
+Create an authentication provider from a cmem-plugin-base context object.
+
+Wraps the token callable exposed by the context's ``UserContext`` in a
+``ProvidedToken`` provider.
+
+**Parameters:**
+
+- **context** (<code>object</code>) – An ``ExecutionContext`` or ``PluginContext`` instance from
+``cmem-plugin-base``. Must expose a ``user`` attribute
+(``UserContext``) with a ``token()`` method that returns a
+valid bearer token.
+
+**Returns:**
+
+- <code>[AuthProvider](#cmem_client.auth_provider.abc.AuthProvider)</code> – A ``ProvidedToken`` authentication provider backed by the
+- <code>[AuthProvider](#cmem_client.auth_provider.abc.AuthProvider)</code> – context's ``UserContext.token()`` method.
+
+### `from_dict` {#cmem_client.auth_provider.abc.AuthProvider.from_dict}
+
+```python
+from_dict(config, d)
+```
+
+Create an authentication provider from a plain dictionary.
+
+Selects and configures the appropriate authentication provider based
+on the ``OAUTH_GRANT_TYPE`` key in the dictionary, defaulting to
+``"client_credentials"`` when not specified.
+
+**Parameters:**
+
+- **config** (<code>[Config](../../config/index.md#cmem_client.config.Config)</code>) – Configuration object containing Corporate Memory connection
+details and endpoint URLs.
+- **d** (<code>dict[str, str]</code>) – Dictionary of configuration values. The ``OAUTH_GRANT_TYPE`` key
+controls which provider is created. Remaining keys are forwarded
+to the selected provider's ``from_dict`` factory.
+
+**Returns:**
+
+- <code>[AuthProvider](#cmem_client.auth_provider.abc.AuthProvider)</code> – A configured AuthProvider instance.
+
+**Raises:**
+
+- <code>[ClientEnvConfigError](../../exceptions/index.md#cmem_client.exceptions.ClientEnvConfigError)</code> – If ``OAUTH_GRANT_TYPE`` is not a supported
+value or if required keys for the selected provider are missing.
+
+### `from_env` {#cmem_client.auth_provider.abc.AuthProvider.from_env}
+
+```python
+from_env(config)
+```
+
+Create an authentication provider from environment variables.
+
+This factory method automatically selects and configures the appropriate
+authentication provider based on the OAUTH_GRANT_TYPE environment variable.
+It supports multiple OAuth 2.0 flows and authentication methods.
+
+**Parameters:**
+
+- **config** (<code>[Config](../../config/index.md#cmem_client.config.Config)</code>) – Configuration object containing Corporate Memory connection
+details and endpoint URLs.
+
+**Returns:**
+
+- <code>[AuthProvider](#cmem_client.auth_provider.abc.AuthProvider)</code> – A configured AuthProvider instance appropriate for the environment
+- <code>[AuthProvider](#cmem_client.auth_provider.abc.AuthProvider)</code> – configuration.
+
+**Raises:**
+
+- <code>[ClientEnvConfigError](../../exceptions/index.md#cmem_client.exceptions.ClientEnvConfigError)</code> – If the OAUTH_GRANT_TYPE is not supported or
+if required environment variables for the selected provider
+are missing.
+
+<details class="environment-variables" open markdown="1">
+<summary>Environment Variables</summary>
+
+OAUTH_GRANT_TYPE (optional): The OAuth flow type. Defaults to
+    "client_credentials". Supported values:
+    - "client_credentials": Client Credentials Flow for M2M auth
+    - "password": Resource Owner Password Flow for trusted apps
+    - "prefetched_token": Use externally obtained access token
+
+</details>
+
+### `get_access_token` {#cmem_client.auth_provider.abc.AuthProvider.get_access_token}
+
+```python
+get_access_token()
+```
+
+Get the access token for Bearer Authorization header.
+
+Also sets the preferred username for the authentication provider via the extracted token.
+
+**Returns:**
+
+- <code>str</code> – A valid access token string.
+
+**Raises:**
+
+- <code>ValueError</code> – If the provider returned no access token.
+
+<details class="note" open markdown="1">
+<summary>Note</summary>
+
+Implementations should handle token refresh logic internally when
+tokens expire, ensuring this method always returns a valid token.
+
+</details>
+
+### `logger` {#cmem_client.auth_provider.abc.AuthProvider.logger}
+
+```python
+logger: logging.Logger
+```
+
+The logger for the auth provider.
+
+### `preferred_username` {#cmem_client.auth_provider.abc.AuthProvider.preferred_username}
+
+```python
+preferred_username: str
+```
+
+The preferred username for the authentication provider.
+
+## `DEFAULT_OAUTH_CLIENT_ID` {#cmem_client.auth_provider.abc.DEFAULT_OAUTH_CLIENT_ID}
+
+```python
+DEFAULT_OAUTH_CLIENT_ID = 'cmem-service-account'
+```
+