update/rebuild docs for 3.0.0 final (#539)

documentation overhaul and rebuild for v3.0.0 release

Author: tim-quix

docs/advanced/dataframe-assignments.md

@@ -3,6 +3,67 @@
 This section aggregates some of the more nuanced rules behind `StreamingDataFrame`
 operation assignments that are mentioned in various places.
 
+
+## Recommendation: Always Assign Operations!
+
+_**You can safely assign any `StreamingDataFrame` operation to a variable, regardless
+of it being [in-place](#valid-in-place-operations) or not.**_
+
+```python
+# NOTE: this is an incomplete stub just to show usage
+from quixstreams import Application
+
+sdf = Application().dataframe()
+sdf = sdf.apply()
+sdf = sdf.update()  # in-place with assigning!
+sdf = sdf.apply().to_topic()
+```
+
+So whenever in doubt, simply assign operations to a variable, even if it won't 
+be referenced afterward.
+
+Once you grow more comfortable with how the various `StreamingDataFrame`operations work, 
+feel free to skip assignments where applicable.
+
+The only time you should _not_ do assignments is [very special edge cases with 
+intermediate operation referencing](#avoid-intermediate-operation-referencing).
+
+## Avoid: Intermediate Operation Referencing
+
+Intermediate operation referencing corresponds to a specific set of `StreamingDataFrame` 
+operations that are assigned as a variable in one assignment step with the intention to
+being used in future ones (often more than once), especially with branching. 
+
+It will NOT work as expected, so avoid it!
+
+It applies only to a few specific use cases:
+
+1. Using a previous `SDF.apply()` as a filter in a later step:
+    - **Recommended**:
+        ```python
+        # `.apply()` in the same assignment step as its filtering use!
+        sdf = sdf[sdf.apply(f)]
+        ```
+    - **Avoid**:
+        ```python
+        my_filter = sdf.apply(f)
+        sdf = sdf[my_filter]
+        ```
+
+2. Using column-based manipulations later (`SDF["col"]` references):
+    - **Recommended**:
+        ```python
+        # column manipulations and assignment on same assignment step!
+        sdf["z"] = sdf["x"] + sdf["y"]
+        ```
+    - **Avoid**:
+        ```python
+        my_sum = sdf["x"] + sdf["y"]
+        sdf["z"] = my_sum
+        ```
+
+**Intermediate operation references will not raise exceptions**, so be careful!
+
 ## Assignment vs "in-place" Patterns
 
 For `StreamingDataFrames`, the general expected pattern is to assign it to a variable 
@@ -17,7 +78,7 @@ sdf = sdf.apply()  # reassign with new operation
 sdf = sdf.apply().apply()  # reassign with chaining
 ```
 
-This is in contrast to an "inplace" (or "discard", "side effect") pattern, where the 
+This is in contrast to an "in-place" (or "discard", "side effect") pattern, where the 
 operation is not assigned:
 
 ```python
@@ -53,11 +114,11 @@ See [sinks](../connectors/sinks/README.md#sinks-are-terminal-operations) for det
 
 With the introduction of branching, assignment is no longer technically required 
 for the "assignment" operation to be added: it instead generates a 
-[terminal branch](branching.md#terminal-branches-no-assignment).
+[terminal branch](../branching.md#terminal-branches-no-assignment).
 
 In general, it is still recommended to follow both the 
 [recommended assignment patterns](#assignment-vs-in-place-patterns) and
-[recommended branching patterns](branching.md#branching-fundamentals).
+[recommended branching patterns](../branching.md#branching-fundamentals).
 
 ## Before Quix Streams v3.0.0 (branching)
 

docs/api-reference/application.md

@@ -10,7 +10,7 @@
 class Application()
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L63)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L63)
 
 The main Application class.
 
@@ -59,6 +59,7 @@ app.run()
 
 ```python
 def __init__(broker_address: Optional[Union[str, ConnectionConfig]] = None,
+             *,
              quix_sdk_token: Optional[str] = None,
              consumer_group: Optional[str] = None,
              auto_offset_reset: AutoOffsetReset = "latest",
@@ -84,7 +85,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/main/quixstreams/app.py#L101)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L101)
 
 
 <br>
@@ -173,7 +174,7 @@ instead of the default one.
 def Quix(cls, *args, **kwargs)
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L355)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L356)
 
 RAISES EXCEPTION: DEPRECATED.
 
@@ -196,7 +197,7 @@ def topic(name: str,
           timestamp_extractor: Optional[TimestampExtractor] = None) -> Topic
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L370)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L371)
 
 Create a topic definition.
 
@@ -278,7 +279,7 @@ def dataframe(topic: Optional[Topic] = None,
               source: Optional[BaseSource] = None) -> StreamingDataFrame
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L450)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L451)
 
 A simple helper method that generates a `StreamingDataFrame`, which is used
 
@@ -334,7 +335,7 @@ to be used as an input topic.
 def stop(fail: bool = False)
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L505)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L506)
 
 Stop the internal poll loop and the message processing.
 
@@ -361,7 +362,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/main/quixstreams/app.py#L550)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L551)
 
 Create and return a pre-configured Producer instance.
 The Producer is initialized with params passed to Application.
@@ -396,7 +397,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/main/quixstreams/app.py#L580)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L581)
 
 Create and return a pre-configured Consumer instance.
 
@@ -453,7 +454,7 @@ with app.get_consumer() as consumer:
 def clear_state()
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L630)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L631)
 
 Clear the state of the application.
 
@@ -467,7 +468,7 @@ Clear the state of the application.
 def add_source(source: BaseSource, topic: Optional[Topic] = None) -> Topic
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L636)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L637)
 
 Add a source to the application.
 
@@ -493,7 +494,7 @@ Default: the source default
 def run(dataframe: Optional[StreamingDataFrame] = None)
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L657)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L658)
 
 Start processing data from Kafka using provided `StreamingDataFrame`
 
@@ -529,7 +530,7 @@ app.run()
 def setup_topics()
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L779)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L780)
 
 Validate and create the topics
 
@@ -541,7 +542,7 @@ Validate and create the topics
 class ApplicationConfig(BaseSettings)
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L955)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L956)
 
 Immutable object holding the application configuration
 
@@ -564,7 +565,7 @@ def settings_customise_sources(
 ) -> Tuple[PydanticBaseSettingsSource, ...]
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L990)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L991)
 
 Included to ignore reading/setting values from the environment
 
@@ -578,7 +579,7 @@ Included to ignore reading/setting values from the environment
 def copy(**kwargs) -> Self
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/app.py#L1003)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/app.py#L1004)
 
 Update the application config and return a copy
 

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/main/quixstreams/context.py#L20)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/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/main/quixstreams/context.py#L51)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/3.0.0-docs/quixstreams/context.py#L51)
 
 Get a MessageContext for the current message, which houses most of the message