docs: Add standalone sources section (#557)

* docs: Add standalone sources section

* indentation

* Sources docs update

---------

Co-authored-by: Daniil Gusev <daniil@quix.io>

Author: ovv

docs/connectors/sources/README.md

@@ -9,41 +9,42 @@ from quixstreams import Application
 from quixstreams.sources import CSVSource
 
 def main():
-  app = Application()
-  source = CSVSource(path="input.csv")
-
-  sdf = app.dataframe(source=source)
-  sdf.print(metadata=True)
-
-  app.run()
-
+    app = Application()
+    source = CSVSource(path="input.csv")
+    
+    sdf = app.dataframe(source=source)
+    sdf.print(metadata=True)
+    
+    app.run()
+    
 if __name__ == "__main__":
-  main()
+    main()
 ```
 
 ## Supported sources
 
-Quix streams provide a source out of the box.
+Quix Streams provides the following sources out of the box:
 
 * [CSVSource](./csv-source.md): A source that reads data from a single CSV file.
 * [KafkaReplicatorSource](./kafka-source.md): A source that replicates a topic from a Kafka broker to your application broker.
 * [QuixEnvironmentSource](./quix-source.md): A source that replicates a topic from a Quix Cloud environment to your application broker.
 
-You can also implement your own, have a look at [Creating a Custom Source](custom-sources.md) for documentation on how to do that.
+To create a custom source, read [Creating a Custom Source](custom-sources.md).
 
 ## Multiprocessing
 
 For good performance, each source runs in a subprocess. Quix Streams automatically manages the subprocess's setting up, monitoring, and tearing down. 
 
 For multiplatform support, Quix Streams starts the source process using the [spawn](https://docs.python.org/3/library/multiprocessing.html#contexts-and-start-methods) approach. As a side effect, each Source instance must be pickleable. If a source needs to handle unpickleable objects, it's best to initialize those in the source subprocess (in the `BaseSource.start` or `Source.run` methods).  
 
-## Topics
+## Customize Topic Configuration
 
-Sources work by sending data to Kafka topics. Then StreamingDataFrames consume these topics.
+Sources work by sending data to intermediate Kafka topics, which StreamingDataFrames then consume and process.
 
-Each source provides a default topic based on its configuration. You can override the default topic by specifying a topic using the `app.dataframe()` method. 
+By default, each Source provides a default topic based on its configuration.  
+To customize the topic config, pass a new `Topic` object to the `app.dataframe()` method together with the Source instance. 
 
-**Example**
+**Example:**
 
 Provide a custom topic with four partitions to the source. 
 
@@ -54,9 +55,14 @@ from quixstreams.models.topics import TopicConfig
 
 def main():
     app = Application()
+    # Create a CSVSource
     source = CSVSource(path="input.csv")
+    
+    # Define a topic for the CSVSource with a custom config
     topic = app.topic("my_csv_source", config=TopicConfig(num_partitions=4, replication_factor=1))
 
+    # Pass the topic together with the CSVSource to a dataframe
+    # When the CSVSource starts, it will produce data to this topic
     sdf = app.dataframe(topic=topic, source=source)
     sdf.print(metadata=True)
 
@@ -65,3 +71,61 @@ def main():
 if __name__ == "__main__":
     main()
 ```
+
+## Standalone sources
+
+So far we have covered how to run Sources and process data within the same application.  
+
+When you scale your processing applications to more instances, you may need to run only a single instance of the Source.  
+For example, when the source is reading data from some Websocket API, and you want to process it with multiple apps.  
+
+To achieve that, Sources can be run in a standalone mode.
+
+**Example**
+
+Running an imaginary Websocket source in a standalone mode to read data only once. 
+
+```python
+from quixstreams import Application
+
+def main():
+    app = Application()
+    
+    # Create an instance of SomeWebsocketSource
+    source = SomeWebsocketSource(url="wss://example.com")
+    
+    # Register the source in the app
+    app.add_source(source)
+    
+    # Start the application
+    # The app will start SomeWebsocketSource, and it will produce data to the default intermediate topic
+    app.run()
+
+if __name__ == "__main__":
+    main()
+```
+
+To customize the topic the Source will use, create a new `Topic` and pass it to the `app.add_source()` method:
+
+```python
+from quixstreams import Application
+from quixstreams.sources import CSVSource
+from quixstreams.models.topics import TopicConfig
+
+def main():
+    app = Application()
+    # Create an instance of SomeWebsocketSource
+    source = SomeWebsocketSource(url="wss://example.com")
+    
+    # Define a topic for the CSVSource with a custom config
+    topic = app.topic("some-websocket-source", config=TopicConfig(num_partitions=4, replication_factor=1))
+    
+    # Register the source and topic in the application
+    app.add_source(source=source, topic=topic)
+    
+    # Start the application
+    app.run()
+
+if __name__ == "__main__":
+    main()
+```

docs/connectors/sources/csv-source.md

@@ -13,16 +13,16 @@ from quixstreams import Application
 from quixstreams.sources import CSVSource
 
 def main():
-  app = Application()
-  source = CSVSource(path="input.csv")
+    app = Application()
+    source = CSVSource(path="input.csv")
 
-  sdf = app.dataframe(source=source)
-  sdf.print(metadata=True)
+    sdf = app.dataframe(source=source)
+    sdf.print(metadata=True)
 
-  app.run()
+    app.run()
 
 if __name__ == "__main__":
-  main()
+    main()
 ```
 
 ## File format

docs/connectors/sources/kafka-source.md

@@ -15,15 +15,15 @@ from quixstreams.sources import KafkaReplicatorSource
 def main():
     app = Application()
     source = KafkaReplicatorSource(
-    name="my-source",
-    app_config=app.config,
-    topic="source-topic",
-    broker_address="source-broker-address"
+      name="my-source",
+      app_config=app.config,
+      topic="source-topic",
+      broker_address="source-broker-address"
     )
-    
+
     sdf = app.dataframe(source=source)
     sdf.print(metadata=True)
-    
+
     app.run()
 
 if __name__ == "__main__":

docs/connectors/sources/quix-source.md

@@ -13,11 +13,11 @@ from quixstreams.sources import QuixEnvironmentSource
 def main():
     app = Application()
     source = QuixEnvironmentSource(
-    name="my-source",
-    app_config=app.config,
-    topic="source-topic",
-    quix_sdk_token="quix-sdk-token",
-    quix_workspace_id="quix-workspace-id",
+      name="my-source",
+      app_config=app.config,
+      topic="source-topic",
+      quix_sdk_token="quix-sdk-token",
+      quix_workspace_id="quix-workspace-id",
     )
 
     sdf = app.dataframe(source=source)