docs: create documentation navigation structure and some examples (#563)

* docs: create documentation navigation structure and some examples

* test: refactor CLI tests without chdir

* test: test custom naming option

* refactor: use only tests directory to store tests

* test: mv all tests to tests dir

* Update mkdocs.yml

docs/docs/en/features.md

@@ -0,0 +1 @@
+# Features

docs/docs/en/getting-started/index.md

@@ -0,0 +1 @@
+# First Steps

docs/docs/en/index.md

@@ -176,7 +176,7 @@ To check the response, we registered an additional `on_output_data` subscriber w
 
 The application can be started using builtin FastStream CLI command.
 
-First we will save our application code to `basic.py` file. Here is the application code again:
+First we will save our application code to `app.py` file. Here is the application code again:
 
 ``` python
 {!> docs_src/kafka/basic/basic.py!}
@@ -185,13 +185,13 @@ First we will save our application code to `basic.py` file. Here is the applicat
 To run the service, use the FastStream CLI command and pass the module (in this case, the file where the app implementation is located) and the app simbol to the command.
 
 ``` shell
-{!> docs_src/kafka/basic/test_cmd.py[ln:11]!}
+faststream run basic:app
 ```
 
 After running the command you should see the following output:
 
 ``` shell
 INFO     - FastStream app starting...
-INFO     - input_data |            - `True` waiting for messages
+INFO     - input_data |            - `OnInputData` waiting for messages
 INFO     - FastStream app started successfully! To exit press CTRL+C
 ```

docs/docs_src/getting_started/context/custom_context_kafka.py

@@ -0,0 +1,41 @@
+from faststream import Context, FastStream, apply_types
+from faststream.kafka import KafkaBroker
+from faststream.kafka.annotations import ContextRepo, KafkaMessage
+
+broker = KafkaBroker("localhost:9092")
+app = FastStream(broker)
+
+
+@broker.subscriber("test-topic")
+async def handle(
+    msg: str,
+    message: KafkaMessage,
+    context: ContextRepo,
+    secret=Context(),
+):
+    with context.scope("correlation_id", message.correlation_id):
+        call_a(secret)
+
+
+@apply_types
+def call_a(s, secret=Context()):  # get from call  # get from global context
+    assert s == secret
+    call_b()
+
+
+@apply_types
+def call_b(
+    message: KafkaMessage,  # get from local context
+    correlation_id=Context(),  # get from local context
+):
+    assert correlation_id == message.correlation_id
+
+
+@app.on_startup
+async def set_global(context: ContextRepo):
+    context.set_global("secret", "my-perfect-secret")
+
+
+@app.after_startup
+async def test():
+    await broker.publish("Hi!", "test-topic")

docs/docs_src/getting_started/context/existed_context_kafka.py

@@ -0,0 +1,50 @@
+from faststream import Context, FastStream
+from faststream.kafka import KafkaBroker
+from faststream.kafka.annotations import (
+    ContextRepo,
+    KafkaMessage,
+    Logger,
+)
+from faststream.kafka.annotations import (
+    KafkaBroker as BrokerAnnotation,
+)
+
+broker_object = KafkaBroker("localhost:9092")
+app = FastStream(broker_object)
+
+
+@broker_object.subscriber("test-topic")
+async def handle(
+    msg: str,
+    logger=Context(),
+    message=Context(),
+    broker=Context(),
+    context=Context(),
+):
+    logger.info(msg)
+    context.set_global("correlation_id", message.correlation_id)
+
+    await broker.publish(
+        "Hi!",
+        topic="response-topic",
+        correlation_id=message.correlation_id,
+    )
+
+
+@broker_object.subscriber("response-topic")
+async def handle_response(
+    msg: str,
+    logger: Logger,
+    message: KafkaMessage,
+    context: ContextRepo,
+    correlation_id=Context(),
+):
+    logger.info(msg)
+
+    assert msg == "Hi!"
+    assert correlation_id == message.correlation_id == context.get("correlation_id")
+
+
+@app.after_startup
+async def test(broker: BrokerAnnotation):
+    await broker.publish("Hi!", "test-topic")

docs/docs_src/getting_started/context/extra_arguments_kafka.py

@@ -0,0 +1,23 @@
+from faststream import Context, FastStream
+from faststream.kafka import KafkaBroker
+from faststream.kafka.annotations import ContextRepo
+
+broker = KafkaBroker("localhost:9092")
+app = FastStream(broker)
+
+
+@broker.subscriber("test-topic")
+async def handle(
+    secret: int = Context("secret_int"),
+    casted_secret: int = Context("secret_int", cast=True),
+    not_existed: None = Context("not_existed", default=None),
+):
+    assert secret == "1"
+    assert casted_secret == 1
+    assert not_existed is None
+
+
+@app.after_startup
+async def test(context: ContextRepo):
+    context.set_global("secret_int", "1")
+    await broker.publish("", "test-topic")

docs/docs_src/getting_started/context/fields_access_kafka.py

@@ -0,0 +1,19 @@
+from faststream import Context, FastStream
+from faststream.kafka import KafkaBroker
+from faststream.kafka.annotations import KafkaMessage
+
+broker = KafkaBroker("localhost:9092")
+app = FastStream(broker)
+
+
+@broker.subscriber("test-topic")
+async def handle(
+    message: KafkaMessage,
+    correlation_id: str = Context("message.correlation_id"),
+):
+    assert message.correlation_id == correlation_id
+
+
+@app.after_startup
+async def test():
+    await broker.publish("", "test-topic")

docs/docs_src/getting_started/dependencies/basic_kafka.py

@@ -0,0 +1,26 @@
+from faststream import Depends, FastStream
+from faststream.kafka import KafkaBroker
+
+broker = KafkaBroker("localhost:9092")
+app = FastStream(broker)
+
+
+async def get_user_from_db(name: str, user_id: int):
+    """Emulate DB request"""
+    return {
+        "name": name,
+        "user_id": user_id,
+    }
+
+
+@broker.subscriber("test-topic")
+async def handle(user=Depends(get_user_from_db)):
+    assert user == {
+        "name": "john",
+        "user_id": 1,
+    }
+
+
+@app.after_startup
+async def test():
+    await broker.publish({"name": "john", "user_id": 1}, topic="test-topic")

docs/docs_src/getting_started/dependencies/class_kafka.py

@@ -0,0 +1,22 @@
+from faststream import Depends, FastStream
+from faststream.kafka import KafkaBroker
+
+broker = KafkaBroker("localhost:9092")
+app = FastStream(broker)
+
+
+class UserSerialized:
+    def __init__(self, name: str, user_id: int):
+        self.name = name
+        self.user_id = user_id
+
+
+@broker.subscriber("test-topic")
+async def handle(user=Depends(UserSerialized)):
+    assert user.name == "john"
+    assert user.user_id == 1
+
+
+@app.after_startup
+async def test():
+    await broker.publish({"name": "john", "user_id": 1}, topic="test-topic")

docs/docs_src/getting_started/dependencies/global_broker_kafka.py

@@ -0,0 +1,27 @@
+from faststream import Depends, FastStream
+from faststream.kafka import KafkaBroker
+
+
+async def validate_user(name: str, user_id: int):
+    """Emulate DB request"""
+    user = {
+        "name": "john",
+        "user_id": user_id,
+    }
+
+    if user["name"] != name:
+        raise ValueError()
+
+
+broker = KafkaBroker("localhost:9092", dependencies=(Depends(validate_user),))
+app = FastStream(broker)
+
+
+@broker.subscriber("test-topic")
+async def handle(name: str):
+    assert name == "john"
+
+
+@app.after_startup
+async def test():
+    await broker.publish({"name": "john", "user_id": 1}, topic="test-topic")

docs/docs_src/getting_started/dependencies/global_kafka.py

@@ -0,0 +1,26 @@
+from faststream import Depends, FastStream
+from faststream.kafka import KafkaBroker
+
+broker = KafkaBroker("localhost:9092")
+app = FastStream(broker)
+
+
+async def validate_user(name: str, user_id: int):
+    """Emulate DB request"""
+    user = {
+        "name": "john",
+        "user_id": user_id,
+    }
+
+    if user["name"] != name:
+        raise ValueError()
+
+
+@broker.subscriber("test-topic", dependencies=(Depends(validate_user),))
+async def handle(name: str):
+    assert name == "john"
+
+
+@app.after_startup
+async def test():
+    await broker.publish({"name": "john", "user_id": 1}, topic="test-topic")

docs/docs_src/getting_started/dependencies/sub_dep_kafka.py

@@ -0,0 +1,30 @@
+from faststream import Depends, FastStream
+from faststream.kafka import KafkaBroker
+
+broker = KafkaBroker("localhost:9092")
+app = FastStream(broker)
+
+
+async def get_user_from_db(user_id: int):
+    """Emulate DB request"""
+    return {
+        "name": "john",
+        "user_id": user_id,
+    }
+
+
+async def validate_db_user(
+    name: str,
+    user=Depends(get_user_from_db),
+):
+    return user["name"] == name
+
+
+@broker.subscriber("test-topic")
+async def handle(is_user_valid=Depends(validate_db_user)):
+    assert is_user_valid
+
+
+@app.after_startup
+async def test():
+    await broker.publish({"name": "john", "user_id": 1}, topic="test-topic")

docs/docs_src/getting_started/dependencies/yield_kafka.py

@@ -0,0 +1,27 @@
+from contextlib import contextmanager
+
+from faststream import Depends, FastStream
+from faststream.kafka import KafkaBroker
+
+broker = KafkaBroker("localhost:9092")
+app = FastStream(broker)
+
+
+@contextmanager
+def fake_session_builder():
+    yield "session"
+
+
+async def db_session():
+    with fake_session_builder() as session:
+        yield session
+
+
+@broker.subscriber("test-topic")
+async def handle(db_session=Depends(db_session)):
+    assert db_session == "session"
+
+
+@app.after_startup
+async def test():
+    await broker.publish("", topic="test-topic")

docs/docs_src/getting_started/lifespan/all_hooks_kafka.py

@@ -0,0 +1,34 @@
+from faststream import ContextRepo, FastStream
+from faststream.kafka import KafkaBroker
+from faststream.kafka.annotations import KafkaBroker as BrokerAnnotation
+
+app = FastStream(KafkaBroker("localhost:9092"))
+
+
+@app.on_startup
+def cli_run(  # sync or async function
+    context: ContextRepo,  # get from global context
+    env: str = ".env",  # get from CLI option `--env=...`
+):
+    context.set_global("use_env", env)
+
+
+@app.after_startup
+async def broker_available(
+    broker: BrokerAnnotation,  # get from global context
+):
+    await broker.publish("Service started", topic="logs")
+
+
+@app.on_shutdown
+async def broker_still_available(
+    broker: BrokerAnnotation,  # get from global context
+):
+    await broker.publish("Service stopped", topic="logs")
+
+
+@app.after_shutdown
+async def broker_stopped(
+    broker: BrokerAnnotation,  # get from global context
+):
+    assert broker._connection is None

docs/docs_src/getting_started/lifespan/testing_kafka.py

@@ -0,0 +1,14 @@
+import pytest
+
+from faststream.kafka import TestKafkaBroker
+
+from .all_hooks_kafka import app
+
+
+@pytest.mark.asyncio
+async def test_lifespan():
+    async with TestKafkaBroker(app.broker):
+
+        async def TestApp(app):
+            # test smth
+            pass