Autogenerate docs (#433)

* Documentation source links to the main branch
This will produce consistent source links that point to the main branch.
It will reduce the amount of noise in the documentation PRs.
* Replace SHA with the main branch in view source links
* Add generate documentation workflow

Author: gwaramadze

.github/workflows/docs.yml

@@ -0,0 +1,30 @@
+name: Generate Documentation
+
+on:
+  push:
+    branches:
+      - main
+
+permissions: { }
+
+jobs:
+  generate-docs:
+    permissions:
+      contents: write
+      pull-requests: write
+    # We have to use a Mac OS image because the documentation generated
+    # on Ubuntu unexpectedly rearranges the contents of quixstreams.md
+    runs-on: macos-latest
+    steps:
+      - uses: actions/checkout@v4
+      - run: pip install -r docs/build/requirements.txt
+      - run: python build.py
+        working-directory: ./docs/build
+      - uses: peter-evans/create-pull-request@v6
+        with:
+          commit-message: Update documentation
+          branch: auto/update-documentation
+          delete-branch: true
+          title: 'Update Documentation'
+          body: 'This is the PR with the autogenerated documentation'
+          labels: 'documentation'

docs/api-reference/application.md

@@ -10,7 +10,7 @@
 class Application()
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/app.py#L56)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L56)
 
 The main Application class.
 
@@ -83,7 +83,7 @@ def __init__(broker_address: Optional[Union[str, ConnectionConfig]] = None,
              processing_guarantee: ProcessingGuarantee = "at-least-once")
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/app.py#L94)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L94)
 
 
 <br>
@@ -186,7 +186,7 @@ def Quix(
 ) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/app.py#L330)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L342)
 
 >***NOTE:*** DEPRECATED: use Application with `quix_sdk_token` argument instead.
 
@@ -297,7 +297,7 @@ def topic(name: str,
           timestamp_extractor: Optional[TimestampExtractor] = None) -> Topic
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/app.py#L471)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L483)
 
 Create a topic definition.
 
@@ -378,7 +378,7 @@ topic = app.topic("input-topic", timestamp_extractor=custom_ts_extractor)
 def dataframe(topic: Topic) -> StreamingDataFrame
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/app.py#L551)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L563)
 
 A simple helper method that generates a `StreamingDataFrame`, which is used
 
@@ -428,7 +428,7 @@ to be used as an input topic.
 def stop(fail: bool = False)
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/app.py#L590)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L602)
 
 Stop the internal poll loop and the message processing.
 
@@ -455,7 +455,7 @@ to unhandled exception, and it shouldn't commit the current checkpoint.
 def get_producer() -> Producer
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/app.py#L613)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L625)
 
 Create and return a pre-configured Producer instance.
 The Producer is initialized with params passed to Application.
@@ -490,7 +490,7 @@ with app.get_producer() as producer:
 def get_consumer(auto_commit_enable: bool = True) -> Consumer
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/app.py#L643)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L655)
 
 Create and return a pre-configured Consumer instance.
 The Consumer is initialized with params passed to Application.
@@ -539,7 +539,7 @@ with app.get_consumer() as consumer:
 def clear_state()
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/app.py#L690)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L702)
 
 Clear the state of the application.
 
@@ -553,7 +553,7 @@ Clear the state of the application.
 def run(dataframe: StreamingDataFrame)
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/app.py#L696)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L708)
 
 Start processing data from Kafka using provided `StreamingDataFrame`
 

docs/api-reference/context.md

@@ -12,7 +12,7 @@
 def set_message_context(context: Optional[MessageContext])
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/context.py#L20)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/context.py#L20)
 
 Set a MessageContext for the current message in the given `contextvars.Context`
 
@@ -55,7 +55,7 @@ sdf = sdf.update(lambda value: alter_context(value))
 def message_context() -> MessageContext
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/context.py#L51)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/context.py#L51)
 
 Get a MessageContext for the current message, which houses most of the message
 

docs/api-reference/dataframe.md

@@ -10,7 +10,7 @@
 class StreamingDataFrame(BaseStreaming)
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L63)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L63)
 
 `StreamingDataFrame` is the main object you will use for ETL work.
 
@@ -81,7 +81,7 @@ def apply(func: Union[
           metadata: bool = False) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L178)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L178)
 
 Apply a function to transform the value and return a new value.
 
@@ -139,7 +139,7 @@ def update(func: Union[
            metadata: bool = False) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L267)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L267)
 
 Apply a function to mutate value in-place or to perform a side effect
 
@@ -207,7 +207,7 @@ def filter(func: Union[
            metadata: bool = False) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L359)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L359)
 
 Filter value using provided function.
 
@@ -259,7 +259,7 @@ def group_by(key: Union[str, Callable[[Any], Any]],
              key_serializer: Optional[SerializerType] = "json") -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L445)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L445)
 
 "Groups" messages by re-keying them via the provided group_by operation
 
@@ -324,7 +324,7 @@ a clone with this operation added (assign to keep its effect).
 def contains(key: str) -> StreamingSeries
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L523)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L523)
 
 Check if the key is present in the Row value.
 
@@ -363,7 +363,7 @@ or False otherwise.
 def to_topic(topic: Topic, key: Optional[Callable[[Any], Any]] = None) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L548)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L548)
 
 Produce current value to a topic. You can optionally specify a new key.
 
@@ -416,7 +416,7 @@ the updated StreamingDataFrame instance (reassignment NOT required).
 def set_timestamp(func: Callable[[Any, Any, int, Any], int]) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L593)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L593)
 
 Set a new timestamp based on the current message value and its metadata.
 
@@ -469,7 +469,7 @@ def set_headers(
 ) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L634)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L634)
 
 Set new message headers based on the current message value and metadata.
 
@@ -518,7 +518,7 @@ a new StreamingDataFrame instance
 def print(pretty: bool = True, metadata: bool = False) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L685)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L685)
 
 Print out the current message value (and optionally, the message metadata) to
 
@@ -574,7 +574,7 @@ def compose(
 ) -> Dict[str, VoidExecutor]
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L727)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L727)
 
 Compose all functions of this StreamingDataFrame into one big closure.
 
@@ -628,7 +628,7 @@ def test(value: Any,
          topic: Optional[Topic] = None) -> List[Any]
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L764)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L764)
 
 A shorthand to test `StreamingDataFrame` with provided value
 
@@ -665,7 +665,7 @@ def tumbling_window(duration_ms: Union[int, timedelta],
                     name: Optional[str] = None) -> TumblingWindowDefinition
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L801)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L801)
 
 Create a tumbling window transformation on this StreamingDataFrame.
 
@@ -751,7 +751,7 @@ def hopping_window(duration_ms: Union[int, timedelta],
                    name: Optional[str] = None) -> HoppingWindowDefinition
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L877)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L877)
 
 Create a hopping window transformation on this StreamingDataFrame.
 
@@ -843,7 +843,7 @@ sdf = (
 def drop(columns: Union[str, List[str]]) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/dataframe.py#L969)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/dataframe.py#L969)
 
 Drop column(s) from the message value (value must support `del`, like a dict).
 
@@ -887,7 +887,7 @@ a new StreamingDataFrame instance
 class StreamingSeries(BaseStreaming)
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L47)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L47)
 
 `StreamingSeries` are typically generated by `StreamingDataframes` when getting
 elements from, or performing certain operations on, a `StreamingDataframe`,
@@ -953,7 +953,7 @@ sdf = sdf[["column_a"] & (sdf["new_sum_field"] >= 10)]
 def from_apply_callback(cls, func: ApplyWithMetadataCallback) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L107)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L107)
 
 Create a StreamingSeries from a function.
 
@@ -981,7 +981,7 @@ instance of `StreamingSeries`
 def apply(func: ApplyCallback) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L121)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L121)
 
 Add a callable to the execution list for this series.
 
@@ -1033,7 +1033,7 @@ a new `StreamingSeries` with the new callable added
 def compose_returning() -> ReturningExecutor
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L155)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L155)
 
 Compose a list of functions from this StreamingSeries and its parents into one
 
@@ -1064,7 +1064,7 @@ def compose(
                             None]] = None) -> VoidExecutor
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L170)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L170)
 
 Compose all functions of this StreamingSeries into one big closure.
 
@@ -1122,7 +1122,7 @@ def test(value: Any,
          ctx: Optional[MessageContext] = None) -> Any
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L214)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L214)
 
 A shorthand to test `StreamingSeries` with provided value
 
@@ -1154,7 +1154,7 @@ result of `StreamingSeries`
 def isin(other: Container) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L269)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L269)
 
 Check if series value is in "other".
 
@@ -1199,7 +1199,7 @@ new StreamingSeries
 def contains(other: Union[Self, object]) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L296)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L296)
 
 Check if series value contains "other"
 
@@ -1244,7 +1244,7 @@ new StreamingSeries
 def is_(other: Union[Self, object]) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L321)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L321)
 
 Check if series value refers to the same object as `other`
 
@@ -1286,7 +1286,7 @@ new StreamingSeries
 def isnot(other: Union[Self, object]) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L344)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L344)
 
 Check if series value does not refer to the same object as `other`
 
@@ -1329,7 +1329,7 @@ new StreamingSeries
 def isnull() -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L368)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L368)
 
 Check if series value is None.
 
@@ -1366,7 +1366,7 @@ new StreamingSeries
 def notnull() -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L391)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L391)
 
 Check if series value is not None.
 
@@ -1403,7 +1403,7 @@ new StreamingSeries
 def abs() -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/78b9db67a528a5423f1795cb3b5747d0f09a8768/quixstreams/dataframe/series.py#L414)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/dataframe/series.py#L414)
 
 Get absolute value of the series value.