Fix/docs fixes (#565)

* Fix links in docs

* Fix Sources docstrings

Author: daniil-quix

docs/branching.md

@@ -134,7 +134,7 @@ Most of branching's limitations are around:
 
 ## Branching Example
 
-In this example, we have purchase events similar to our [purchase-filtering tutorial](../tutorials/purchase-filtering):
+In this example, we have purchase events similar to our [purchase-filtering tutorial](tutorials/purchase-filtering/tutorial.md):
 
 In short, customers who have either a `Gold`, `Silver`, or `Bronze` membership
 are making purchases at this store.

docs/connectors/sinks/README.md

@@ -43,7 +43,7 @@ This is to ensure no further mutations can be applied to the outbound data.
 _However_, you can continue other operations with other branches, including using
 the same `Sink` to push another value (with another `SDF.sink()` call).
 
-[Learn more about _branching_ here](../../advanced/branching.md).
+[Learn more about _branching_ here](../../branching.md).
 
 ### Branching after SDF.sink()
 

docs/connectors/sources/custom-sources.md

@@ -2,8 +2,8 @@
 
 Quix Streams also provides a set of classes to help users implement custom sources.
 
-* [`quixstreams.sources.base.Source`](../../api-reference/sources.md#sources): A subclass of `BaseSource` that implements some helpful methods for writing sources. We recommend subclassing `Source` instead of `BaseSource`.
-* [`quixstreams.sources.base.BaseSource`](../../api-reference/sources.md#BaseSource): This is the base class for all other sources. It defines the must have methods.
+* [`quixstreams.sources.base.Source`](../../api-reference/sources.md#source): A subclass of `BaseSource` that implements some helpful methods for writing sources. We recommend subclassing `Source` instead of `BaseSource`.
+* [`quixstreams.sources.base.BaseSource`](../../api-reference/sources.md#basesource): This is the base class for all other sources. It defines the must-have methods.
 
 ## Source
 

docs/connectors/sources/quix-source.md

@@ -31,4 +31,4 @@ if __name__ == "__main__":
 
 ## SDK Token
 
-The Quix Environment Source requires the SDK token of the source environment. [Click here](../../../develop/authentication/streaming-token.md) for more information on SDK tokens.
+The Quix Environment Source requires the SDK token of the source environment. [Click here](https://quix.io/docs/develop/authentication/streaming-token.html) for more information on SDK tokens.

docs/processing.md

@@ -439,7 +439,7 @@ Since version 2.6, the `StreamingDataFrame.to_topic()` method always forwards th
 
 This way, **the outgoing messages will be produced with the identical timestamps and headers as they were received with** by default. 
 
-To change the timestamp of the message, use the `StreamingDataFrame.set_timestamp()` API, described in [this section](#updating-timestamps).
+To change the timestamp of the message, use the `StreamingDataFrame.set_timestamp()` API, described in [this section](#updating-kafka-timestamps).
 
 ## Using Columns and DataFrame API
 
@@ -673,7 +673,7 @@ To update the current timestamp, use the `StreamingDataFrame.set_timestamp()` AP
 
 There are several things to note:
 
-- The new timestamp will be used by the `StreamingDataFrame.to_topic()` method when the message is produced (see [here](#timestamps-of-produced-messages)).
+- The new timestamp will be used by the `StreamingDataFrame.to_topic()` method when the message is produced (see [here](#timestamps-and-headers-of-produced-messages)).
 - The timestamp will also determine the applicable window in the windowed aggregations.
 
 **Example:**
@@ -757,7 +757,7 @@ The `quixstreams.message_context()` function should be called
 only from the custom functions during processing.
 
 > **_NOTE:_** Before quixstreams==2.6.0, `MessageContext` also provided access to message keys and timestamps.  
-> To access keys and timestamps in `quixstreams>=2.6`, use the approach described in this [section](#accessing-kafka-keys-anad-timestamps)
+> To access keys and timestamps in `quixstreams>=2.6`, use the approach described in this [section](#accessing-kafka-keys-timestamps-and-headers)
 
 
 **Example:**

docs/tutorials/anomaly-detection/tutorial.md

@@ -206,7 +206,7 @@ NOTE: because we use "Current" windowing, we may produce a lot of "duplicate" al
 ### 1. Run Kafka
 First, have a running Kafka cluster. 
 
-To conveniently follow along with this tutorial, just [run this simple one-liner](../tutorials-overview.md#running-kafka-locally).
+To conveniently follow along with this tutorial, just [run this simple one-liner](../README.md#running-kafka-locally).
 
 ### 2. Install Quix Streams
 In your python environment, run `pip install quixstreams`

docs/tutorials/purchase-filtering/tutorial.md

@@ -285,7 +285,7 @@ NOTE: by default, our outgoing Kafka key is persisted from the input message.
 ### 1. Run Kafka
 First, have a running Kafka cluster. 
 
-To conveniently follow along with this tutorial, just [run this simple one-liner](../tutorials-overview.md#running-kafka-locally).
+To conveniently follow along with this tutorial, just [run this simple one-liner](../README.md#running-kafka-locally).
 
 ### 2. Install Quix Streams
 In your python environment, run `pip install quixstreams`

docs/tutorials/word-count/tutorial.md

@@ -214,7 +214,7 @@ NOTE: This is how you would see the values in the Kafka topic `product_review_wo
 ### 1. Run Kafka
 First, have a running Kafka cluster. 
 
-To conveniently follow along with this tutorial, just [run this simple one-liner](../tutorials-overview.md#running-kafka-locally).
+To conveniently follow along with this tutorial, just [run this simple one-liner](../README.md#running-kafka-locally).
 
 ### 2. Install Quix Streams
 In your python environment, run `pip install quixstreams`

quixstreams/sources/base/source.py

@@ -26,38 +26,58 @@ class BaseSource(ABC):
     Sources are executed in a sub-process of the main application.
 
     To create your own source you need to implement:
-        * `run`
-        * `stop`
-        * `default_topic`
+
+    * `start`
+    * `stop`
+    * `default_topic`
 
     `BaseSource` is the most basic interface, and the framework expects every
-    sources to implement it. Use `Source` to benefit from a base implementation.
+    source to implement it.
+    Use `Source` to benefit from a base implementation.
 
     You can connect a source to a StreamingDataframe using the Application.
 
     Example snippet:
 
     ```python
-    from quixstreams import Application
-    from quixstreams.sources import Source
+    class RandomNumbersSource(BaseSource):
+    def __init__(self):
+        super().__init__()
+        self._running = False
+
+    def start(self):
+        self._running = True
+
+        while self._running:
+            number = random.randint(0, 100)
+            serialized = self._producer_topic.serialize(value=number)
+            self._producer.produce(
+                topic=self._producer_topic.name,
+                key=serialized.key,
+                value=serialized.value,
+            )
+
+    def stop(self):
+        self._running = False
+
+    def default_topic(self) -> Topic:
+        return Topic(
+            name="topic-name",
+            value_deserializer="json",
+            value_serializer="json",
+        )
 
-    class MySource(Source):
-        def run(self):
-            for _ in range(1000):
-                self.produce(
-                    key="foo",
-                    value=b"foo"
-                )
 
     def main():
-        app = Application()
-        source = MySource(name="my_source")
+        app = Application(broker_address="localhost:9092")
+        source = RandomNumbersSource()
 
         sdf = app.dataframe(source=source)
         sdf.print(metadata=True)
 
         app.run()
 
+
     if __name__ == "__main__":
         main()
     ```
@@ -104,23 +124,6 @@ def stop(self) -> None:
         This method is triggered when the application is shutting down.
 
         The source must ensure that the `run` method is completed soon.
-
-        Example Snippet:
-
-        ```python
-        class MySource(BaseSource):
-            def start(self):
-                self._running = True
-                while self._running:
-                    self._producer.produce(
-                        topic=self._producer_topic,
-                        value="foo",
-                    )
-                    time.sleep(1)
-
-            def stop(self):
-                self._running = False
-        ```
         """
 
     @abstractmethod
@@ -134,22 +137,50 @@ def default_topic(self) -> Topic:
 
 class Source(BaseSource):
     """
-    BaseSource class implementation providing
+    A base class for custom Sources that provides a basic implementation of `BaseSource`
+    interface.
+    It is recommended to interface to create custom sources.
 
-    Implementation for the abstract method:
-        * `default_topic`
-        * `start`
-        * `stop`
+    Subclass it and implement the `run` method to fetch data and produce it to Kafka.
 
-    Helper methods
-        * serialize
-        * produce
-        * flush
+    Example:
 
-    Helper property
-        * running
+    ```python
+    from quixstreams import Application
+    import random
 
-    Subclass it and implement the `run` method to fetch data and produce it to Kafka.
+    from quixstreams.sources import Source
+
+
+    class RandomNumbersSource(Source):
+        def run(self):
+            while self.running:
+                number = random.randint(0, 100)
+                serialized = self._producer_topic.serialize(value=number)
+                self.produce(key=str(number), value=serialized.value)
+
+
+    def main():
+        app = Application(broker_address="localhost:9092")
+        source = RandomNumbersSource(name="random-source")
+
+        sdf = app.dataframe(source=source)
+        sdf.print(metadata=True)
+
+        app.run()
+
+
+    if __name__ == "__main__":
+        main()
+    ```
+
+
+    Helper methods and properties:
+
+    * `serialize()`
+    * `produce()`
+    * `flush()`
+    * `running`
     """
 
     def __init__(self, name: str, shutdown_timeout: float = 10) -> None:
@@ -171,18 +202,6 @@ def running(self) -> bool:
         Property indicating if the source is running.
 
         The `stop` method will set it to `False`. Use it to stop the source gracefully.
-
-        Example snippet:
-
-        ```python
-        class MySource(Source):
-            def run(self):
-                while self.running:
-                    self.produce(
-                        value="foo",
-                    )
-                    time.sleep(1)
-        ```
         """
         return self._running
 
@@ -192,7 +211,7 @@ def cleanup(self, failed: bool) -> None:
 
         Use it to clean up the resources and shut down the source gracefully.
 
-        It flush the producer when `_run` completes successfully.
+        It flushes the producer when `_run` completes successfully.
         """
         if not failed:
             self.flush(self.shutdown_timeout / 2)