Update documentation (#566)

Co-authored-by: daniil-quix <133032822+daniil-quix@users.noreply.github.com>

Author: github-actions[bot]

docs/api-reference/quixstreams.md

@@ -9098,38 +9098,58 @@ This is the base class for all sources.
 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()
 ```
@@ -9142,7 +9162,7 @@ if __name__ == "__main__":
 def configure(topic: Topic, producer: RowProducer) -> None
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L74)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L94)
 
 This method is triggered when the source is registered to the Application.
 
@@ -9157,7 +9177,7 @@ It configures the source's Kafka producer and the topic it will produce to.
 def start() -> None
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L93)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L113)
 
 This method is triggered in the subprocess when the source is started.
 
@@ -9173,29 +9193,12 @@ Use it to fetch data and produce it to Kafka.
 def stop() -> None
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L102)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L122)
 
 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
-```
-
 <a id="quixstreams.sources.base.source.BaseSource.default_topic"></a>
 
 #### BaseSource.default\_topic
@@ -9205,7 +9208,7 @@ class MySource(BaseSource):
 def default_topic() -> Topic
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L127)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L130)
 
 This method is triggered when the topic is not provided to the source.
 
@@ -9219,24 +9222,53 @@ The source must return a default topic configuration.
 class Source(BaseSource)
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L135)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L138)
+
+A base class for custom Sources that provides a basic implementation of `BaseSource`
+interface.
+It is recommended to interface to create custom sources.
 
-BaseSource class implementation providing
+Subclass it and implement the `run` method to fetch data and produce it to Kafka.
 
-Implementation for the abstract method:
-    * `default_topic`
-    * `start`
-    * `stop`
+**Example**:
 
-Helper methods
-    * serialize
-    * produce
-    * flush
+  
+```python
+from quixstreams import Application
+import random
 
-Helper property
-    * running
+from quixstreams.sources import Source
 
-Subclass it and implement the `run` method to fetch data and produce it to Kafka.
+
+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`
 
 <a id="quixstreams.sources.base.source.Source.__init__"></a>
 
@@ -9246,7 +9278,7 @@ Subclass it and implement the `run` method to fetch data and produce it to Kafka
 def __init__(name: str, shutdown_timeout: float = 10) -> None
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L155)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L186)
 
 **Arguments**:
 
@@ -9262,24 +9294,12 @@ def __init__(name: str, shutdown_timeout: float = 10) -> None
 def running() -> bool
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L169)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L200)
 
 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)
-```
-
 <a id="quixstreams.sources.base.source.Source.cleanup"></a>
 
 #### Source.cleanup
@@ -9288,13 +9308,13 @@ class MySource(Source):
 def cleanup(failed: bool) -> None
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L189)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L208)
 
 This method is triggered once the `run` method completes.
 
 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.
 
 <a id="quixstreams.sources.base.source.Source.stop"></a>
 
@@ -9304,7 +9324,7 @@ It flush the producer when `_run` completes successfully.
 def stop() -> None
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L200)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L219)
 
 This method is triggered when the application is shutting down.
 
@@ -9318,7 +9338,7 @@ It sets the `running` property to `False`.
 def start()
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L209)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L228)
 
 This method is triggered in the subprocess when the source is started.
 
@@ -9333,7 +9353,7 @@ It marks the source as running, execute it's run method and ensure cleanup happe
 def run()
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L225)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L244)
 
 This method is triggered in the subprocess when the source is started.
 
@@ -9351,7 +9371,7 @@ def serialize(key: Optional[object] = None,
               timestamp_ms: Optional[int] = None) -> KafkaMessage
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L233)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L252)
 
 Serialize data to bytes using the producer topic serializers and return a `quixstreams.models.messages.KafkaMessage`.
 
@@ -9373,7 +9393,7 @@ def produce(value: Optional[Union[str, bytes]] = None,
             buffer_error_max_tries: int = 3) -> None
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L249)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L268)
 
 Produce a message to the configured source topic in Kafka.
 
@@ -9385,7 +9405,7 @@ Produce a message to the configured source topic in Kafka.
 def flush(timeout: Optional[float] = None) -> None
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L274)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L293)
 
 This method flush the producer.
 
@@ -9408,7 +9428,7 @@ None use producer default or -1 is infinite. Default: None
 def default_topic() -> Topic
 ```
 
-[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L292)
+[[VIEW SOURCE]](https://github.com/quixio/quix-streams/blob/main/quixstreams/sources/base/source.py#L311)
 
 Return a default topic matching the source name.