Update RST docs to MD format

Look man sphinx is powerful and all but pdoc just deals with Pydantic

Author: Epse

.github/workflows/pdoc.yml

@@ -26,7 +26,7 @@ jobs:
       - uses: actions/setup-python@v6
         with:
           python-version: '3.14'
-      - run: uv run pdoc ./src/obelisk -o docs/
+      - run: uv run pdoc ./src/obelisk -o docs/ --math
       - uses: actions/upload-pages-artifact@v4
         with:
           path: docs/

src/obelisk/__init__.py

@@ -3,18 +3,79 @@
 We support both "classic" Obelisk and HFS,
 each with a synchronous and async API.
 We also support Obelisk CORE, in async only for now.
-The PyPi package name is ``obelisk-py``, the Python module is called ``obelisk``.
 
-Your starting point will be one of the Obelisk instances in :mod:`~.sync` or :mod:`~.asynchronous` depending on your preferred API.
+The PyPi package name is `obelisk-py`, the Python module is called `obelisk`.
+
+Your starting point will be one of the Obelisk instances in `.sync` or `.asynchronous` depending on your preferred API.
 
 The Obelisk classes in these modules both implement the same interface,
 but the asynchronous implementation returns Coroutines.
 
-Error handling
---------------
+## Error handling
 
 Obelisk-py comes with robust retry logic to handle any errors that may come up.
 Issues like timeouts, temporary server errors or even DNS issues are fairly common, and handling them properly is important.
-Each Client accepts a retry strategy of type :class:`~.strategies.retry.RetryStrategy`.
-Several predefined strategies are available in :mod:`.strategies.retry`.
+Each Client accepts a retry strategy of type `.strategies.retry.RetryStrategy`.
+Several predefined strategies are available in `.strategies.retry`.
+
+## Quick Start
+
+Using CORE
+```py
+from obelisk.asynchronous.core import Client, QueryParams
+from obelisk.types.core import Filter, Comparison
+import os
+import asyncio
+
+client_id = os.getenv('CLIENT_ID')
+client_secret = os.getenv('CLIENT_SECRET')
+
+# You may want to specify a retry strategy
+client = Client(
+    client=client_id,
+    secret=client_secret
+)
+
+query = QueryParams(
+    dataset="some-dataset",
+    fields=["metric","labels","value","timestamp"],
+    dataType="number",
+    filter_=Filter().add_and(
+        Comparison.equal("metric", "heart_rate::number"),
+        Comparison.greater("timestamp", 42069180)
+    )
+
+data = asyncio.get_event_loop().run_until_complete(client.query(query))
+```
+
+Using Classic or HFS, synchronously (async is analogous)
+```py
+from obelisk.sync import Client
+from obelisk.types import ObeliskKind
+import os
+
+client_id = os.getenv('CLIENT_ID')
+client_secret = os.getenv('CLIENT_SECRET')
+
+# You may want to specify a retry strategy
+client = Client(
+    client=client_id,
+    secret=client_secret,
+    kind=ObeliskKind.CLASSIC # or HFS, as you wish
+)
+
+data = client.query(
+    datasets=["some-dataset"],
+    metrics=["heart-rate::number"],
+    from_timestamp=42069180,
+    filter_={
+        "source": {
+            "_startsWith": "user123"
+        }
+    }
+)
+```
+
+## Changelog
+.. include:: ../../CHANGELOG.rst
 """

src/obelisk/asynchronous/client.py

@@ -18,6 +18,9 @@ class Obelisk(BaseClient):
     Component that contains all the logic to consume data from
     the Obelisk API (e.g. historical data, sse).
 
+    For most usecases, `query` will be the method you need.
+    Have a look at `query_time_chunked` too, because it might just be very useful.
+
     Obelisk API Documentation:
     https://obelisk.docs.apiary.io/
     """
@@ -42,34 +45,34 @@ async def fetch_single_chunk(
         Parameters
         ----------
 
-        datasets : List[str]
+        - datasets:
             List of Dataset IDs.
-        metrics : Optional[List[str]] = None
+        - metrics:
             List of Metric IDs or wildcards (e.g. `*::number`), defaults to all metrics.
-        fields : Optional[List[str]] = None
+        - fields:
             List of fields to return in the result set.
             Defaults to `[metric, source, value]`
-        from_timestamp : Optional[int] = None
+        - from_timestamp:
             Limit output to events after (and including)
             this UTC millisecond timestamp, if present.
-        to_timestamp : Optional[int] = None
+        - to_timestamp:
             Limit output to events before (and excluding)
             this UTC millisecond timestamp, if present.
-        order_by : Optional[dict] = None
+        - order_by:
             Specifies the ordering of the output,
             defaults to ascending by timestamp.
             See Obelisk docs for format. Caller is responsible for validity.
-        filter_ : Optional[dict] = None
+        - filter_:
             Limit output to events matching the specified Filter expression.
             See Obelisk docs, caller is responsible for validity.
-        limit : Optional[int] = None
+        - limit:
             Limit output to a maximum number of events.
             Also determines the page size.
             Default is server-determined, usually 2500.
-        limit_by : Optional[dict] = None
+        - limit_by:
             Limit the combination of a specific set of Index fields
             to a specified maximum number.
-        cursor : Optional[str] = None
+        - cursor:
             Specifies the next cursor,
             used when paging through large result sets.
         """
@@ -129,31 +132,31 @@ async def query(
         Parameters
         ----------
 
-        datasets : List[str]
+        - datasets:
             List of Dataset IDs.
-        metrics : Optional[List[str]] = None
+        - metrics:
             List of Metric IDs or wildcards (e.g. `*::number`), defaults to all metrics.
-        fields : Optional[List[str]] = None
+        - fields:
             List of fields to return in the result set.
             Defaults to `[metric, source, value]`
-        from_timestamp : Optional[int] = None
+        - from_timestamp:
             Limit output to events after (and including)
             this UTC millisecond timestamp, if present.
-        to_timestamp : Optional[int] = None
+        - to_timestamp:
             Limit output to events before (and excluding)
             this UTC millisecond timestamp, if present.
-        order_by : Optional[dict] = None
+        - order_by:
             Specifies the ordering of the output,
             defaults to ascending by timestamp.
             See Obelisk docs for format. Caller is responsible for validity.
-        filter_ : Optional[dict] = None
+        - filter_:
             Limit output to events matching the specified Filter expression.
             See Obelisk docs, caller is responsible for validity.
-        limit : Optional[int] = None
+        - limit:
             Limit output to a maximum number of events.
             Also determines the page size.
             Default is server-determined, usually 2500.
-        limit_by : Optional[dict] = None
+        - limit_by:
             Limit the combination of a specific set of Index fields
             to a specified maximum number.
         """
@@ -209,19 +212,19 @@ async def query_time_chunked(
         Parameters
         ----------
 
-        datasets : List[str]
+        - datasets:
             Dataset IDs to query from
-        metrics : List[str]
+        - metrics:
             IDs of metrics to query
-        from_time : `datetime.datetime`
+        - from_time:
             Start time to fetch from
-        to_time : `datetime.datetime`
+        - to_time:
             End time to fetch until.
-        jump : `datetime.timedelta`
+        - jump:
             Size of one yielded chunk
-        filter_ : Optional[dict] = None
+        - filter_:
             Obelisk filter, caller is responsible for correct format
-        direction : Literal['asc', 'desc'] = 'asc'
+        - direction:
             Yield older data or newer data first, defaults to older first.
         """
 
@@ -249,23 +252,23 @@ async def send(
 
         Parameters
         ----------
-        dataset : str
+        - dataset:
             ID for the dataset to publish to
-        data : List[dict]
+        - data:
             List of Obelisk-acceptable datapoints.
             Exact format varies between Classic or HFS,
             caller is responsible for formatting.
-        precision : :class:`~obelisk.types.TimestampPrecision` = TimestampPrecision.MILLISECONDS
+        - precision:
             Precision used in the numeric timestamps contained in data.
             Ensure it matches to avoid weird errors.
-        mode : :class:`~obelisk.types.IngestMode` = IngestMode.DEFAULT
-            See docs for :class:`~obelisk.types.IngestMode`.
+        - mode:
+            See docs for `obelisk.types.IngestMode`.
 
         Raises
         ------
 
         ObeliskError
-            When the resulting status code is not 204, an empty :exc:`~obelisk.exceptions.ObeliskError` is raised.
+            When the resulting status code is not 204, an empty `obelisk.exceptions.ObeliskError` is raised.
         """
 
         params = {

src/obelisk/asynchronous/core.py

@@ -1,8 +1,8 @@
 """
 This module contains the asynchronous API to interface with Obelisk CORE.
-These methods all return a :class:`Awaitable`.
+These methods all return a `Awaitable`.
 
-Relevant entrance points are :class:`Client`.
+Relevant entrance points are `Client`.
 
 This API vaguely resembles that of clients to previous Obelisk versions,
 but also significantly diverts from it where the underlying Obelisk CORE API does so.
@@ -87,7 +87,7 @@ class ObeliskPosition(BaseModel):
 
 class IncomingDatapoint(BaseModel):
     """A datapoint to be submitted to Obelisk. These are validated quite extensively, but not fully.
-    .. automethod:: check_metric_type(self)
+    We check roughly if the value type corresponds to the declared type if its one of `number`, `number[]`, `bool` or `string`.
     """
 
     timestamp: AwareDatetime | None = None
@@ -133,20 +133,29 @@ def serialize_comma_string(input: Any, handler: SerializerFunctionWrapHandler) -
 
 
 class QueryParams(BaseModel):
+    """
+    To avoid having too many parameters on query functions,
+    and sharing the implementation between query and chunked query,
+    this model collects the information needed to execute a query.
+
+    Contrary to the name, this does not correlate directly to URL query parameters sent to Obelisk.
+    """
     dataset: str
     groupBy: Annotated[list[FieldName] | None, WrapSerializer(serialize_comma_string)] = None
+    """List of Field Names to aggregate by as defined in Obelisk docs, None selects the server-side defaults."""
     aggregator: Aggregator | None = None
     fields: Annotated[list[FieldName] | None, WrapSerializer(serialize_comma_string)] = None
-    orderBy: Annotated[list[str] | None, WrapSerializer(serialize_comma_string)] = (
-        None  # More complex than just FieldName, can be prefixed with - to invert sort
-    )
+    """List of Field Names as defined in Obelisk docs, None selects the server-side defaults."""
+    orderBy: Annotated[list[str] | None, WrapSerializer(serialize_comma_string)] = None
+    """List of Field Names, with their potential prefixes and suffixes, to select ordering. None user server defaults."""
     dataType: DataType | None = None
+    """Data type expected to be returned, is mandatory if the `value` field is requested in the `fields` parameter"""
     filter_: Annotated[str | Filter | None, Field(serialization_alias="filter")] = None
     """
-    Obelisk CORE handles filtering in `RSQL format <https://obelisk.pages.ilabt.imec.be/obelisk-core/query.html#rsql-format>`__ ,
-    to make it easier to also programatically write these filters, we provide the :class:`Filter` option as well.
+    Obelisk CORE handles filtering in [RSQL format](https://obelisk.pages.ilabt.imec.be/obelisk-core/query.html#rsql-format),
+    to make it easier to also programatically write these filters, we provide the `obelisk.types.core.Filter` option as well.
 
-    Suffix to avoid collisions.
+    Suffix to avoid collisions with builtin Python filter function.
     """
     cursor: str | None = None
     limit: int = 1000
@@ -161,10 +170,16 @@ def check_datatype_needed(self) -> Self:
         return self
 
     def to_dict(self) -> dict[str, Any]:
-        return self.model_dump(exclude_none=True, by_alias=True, mode='json')
+        return self.model_dump(exclude_none=True, by_alias=True, mode='json', exclude={"dataset"})
 
 
 class ChunkedParams(BaseModel):
+    """
+    The parameters to be used with `Client.query_time_chunked`,
+    which allows fetching large spans of data in specified "chunks" specified in time units,
+    for example processing weeks of data one hour at a time.
+    This limits memory useage.
+    """
     dataset: str
     groupBy: list[FieldName] | None = None
     aggregator: Aggregator | None = None
@@ -178,6 +193,7 @@ class ChunkedParams(BaseModel):
     start: datetime
     end: datetime
     jump: timedelta = timedelta(hours=1)
+    """The size of one chunk. 1 hour is a common default. You will receive however many datapoints are included in this interval."""
 
     model_config = ConfigDict(arbitrary_types_allowed=True)
 
@@ -189,6 +205,7 @@ def check_datatype_needed(self) -> Self:
         return self
 
     def chunks(self) -> Iterator[QueryParams]:
+        """Splits this model into an Iterator of ordinary `QueryParams` objects, to query one timestep at a time."""
         current_start = self.start
         while current_start < self.end:
             current_end = current_start + self.jump
@@ -210,19 +227,36 @@ def chunks(self) -> Iterator[QueryParams]:
 
 
 class QueryResult(BaseModel):
+    """The data returned by a single chunk fetch"""
     cursor: str | None = None
+    """Cursors always point to the next page of data matched by filters.
+    They are none if there is no more data, they do not consider datapoint count limits."""
     items: list[Datapoint]
 
 
 class Client(BaseClient):
+    """
+    This class performs all communication with Obelisk.
+
+    The intended methods to be used by consumers are `query` or `query_time_chunked`.
+    These will respectively return all data matching specified parameters,
+    or return all data, one timestep at a time respectively.
+
+    `send` is considered an implementation detail,
+    but may be used by consumers for any endpoints not yet implemented by obelisk-py.
+
+    `fetch_single_chunk` is the underlying layer to both query methods and requires the user to handle cursors themselves.
+    It may however still be useful in some circumstances.
+    """
+
     page_limit: int = 250
     """How many datapoints to request per page in a cursored fetch"""
 
     def __init__(
         self,
         client: str,
         secret: str,
-        retry_strategy: RetryStrategy = NoRetryStrategy(),  # noqa: B008   # This is fine to bew shared
+        retry_strategy: RetryStrategy = NoRetryStrategy(),  # noqa: B008   # This is fine to be shared
     ) -> None:
         BaseClient.__init__(
             self,
@@ -242,18 +276,18 @@ async def send(
 
         Parameters
         ----------
-        dataset : str
+        - dataset
             ID for the dataset to publish to
-        data : List[IncomingDatapoint]
+        - data
             List of Obelisk-acceptable datapoints.
             Exact format varies between Classic or HFS,
             caller is responsible for formatting.
 
         Raises
         ------
 
-        ObeliskError
-            When the resulting status code is not 204, an :exc:`~obelisk.exceptions.ObeliskError` is raised.
+        - ObeliskError
+            When the resulting status code is not 204, an `obelisk.exceptions.ObeliskError` is raised.
         """
 
         response = await self.http_post(