docs: add raw docs pages description (#567)

* docs: add raw docs pages description

* test: revert Kafka message key test

* docs (#516): add mike versioning"

* added build docs to pre-commit

* Use load_config to get mkdocs config

* Fix bugs with generating faststream_gen docs

* Update README and faststream_gen docs

* minor fixes

* build docs added to pre-commit hook

---------

Co-authored-by: Davor Runje <[email protected]>
Co-authored-by: Kumaran Rajendhiran <[email protected]>

.faststream_gen/CONTRIBUTING.md

@@ -0,0 +1,118 @@
+## Developing
+
+If you already cloned the repository and you know that you need to deep dive in the code, here are some guidelines to set up your environment.
+
+### Virtual environment with `venv`
+
+You can create a virtual environment in a directory using Python's `venv` module:
+
+```bash
+python -m venv venv
+```
+
+That will create a directory `./venv/` with the Python binaries and then you will be able to install packages for that isolated environment.
+
+### Activate the environment
+
+Activate the new environment with:
+
+```bash
+source ./venv/bin/activate
+```
+
+Make sure you have the latest pip version on your virtual environment to
+
+```bash
+python -m pip install --upgrade pip
+```
+
+### pip
+
+After activating the environment as described above:
+
+```bash
+pip install -e ".[dev]"
+```
+
+It will install all the dependencies and your local FastStream in your local environment.
+
+#### Using your local FastStream
+
+If you create a Python file that imports and uses FastStream, and run it with the Python from your local environment, it will use your local FastStream source code.
+
+And if you update that local FastStream source code, as it is installed with `-e`, when you run that Python file again, it will use the fresh version of FastStream you just edited.
+
+That way, you don't have to "install" your local version to be able to test every change.
+
+To use your local FastStream cli type:
+
+```bash
+python -m faststream ...
+```
+
+### Tests
+
+#### Pytest
+
+To run tests with your current FastStream application and Python environment use:
+
+```bash
+pytest tests
+# or
+./scripts/test.sh
+# with coverage output
+./scripts/test-cov.sh -m "all"
+```
+
+There are some *pytest marks* at project:
+
+* **slow**
+* **rabbit**
+* **kafka**
+* **all**
+
+Default *pytest* calling runs "not slow" tests.
+
+To run all tests use:
+
+```bash
+pytest -m 'all'
+```
+
+Also if you didn't up local rabbit or kafka intance, run tests without that dependencies
+
+```bash
+pytest -m 'not rabbit and not kafka'
+```
+
+To run all tests based on RabbitMQ, Kafka or another dependencies you should run first following *docker-compose.yml*
+
+```yaml
+version: "3"
+
+services:
+    rabbitmq:
+        image: rabbitmq:alpine
+        ports:
+          - "5672:5672"
+    kafka:
+        image: bitnami/kafka:3.5.0
+        ports:
+          - "9092:9092"
+        environment:
+          KAFKA_ENABLE_KRAFT: "true"
+          KAFKA_CFG_NODE_ID: "1"
+          KAFKA_CFG_PROCESS_ROLES: "broker,controller"
+          KAFKA_CFG_CONTROLLER_LISTENER_NAMES: "CONTROLLER"
+          KAFKA_CFG_LISTENERS: "PLAINTEXT://:9092,CONTROLLER://:9093"
+          KAFKA_CFG_LISTENER_SECURITY_PROTOCOL_MAP: "CONTROLLER:PLAINTEXT,PLAINTEXT:PLAINTEXT"
+          KAFKA_CFG_ADVERTISED_LISTENERS: "PLAINTEXT://127.0.0.1:9092"
+          KAFKA_BROKER_ID: "1"
+          KAFKA_CFG_CONTROLLER_QUORUM_VOTERS: "1@kafka:9093"
+          ALLOW_PLAINTEXT_LISTENER: "true"
+
+```
+
+```bash
+docker compose up -d
+```

.faststream_gen/contact.md

@@ -0,0 +1,3 @@
+# Contact FastStream
+
+Media information about creators, how to contact them and the project media pages

.faststream_gen/features.md

@@ -1 +1,19 @@
-# Features
+# Features
+
+Should be as simple as possible, we are making PR for junior, not senior users
+
+Inspirations:
+* FastAPI: https://fastapi.tiangolo.com/features
+* Propan Readme: https://githib.com/Lancetnik/Propan
+
+Pydantic and AsyncAPI - based, support all Pydantic features, etc
+
+Core features overview:
+
+* multiple brokers support
+* pydantic validation (annotation-based/model)
+* automtic docs (with images)
+* editor support (full typed)
+* powerfull dependency injection system
+* testable (in-memory tests)
+* extendable (lifespans, custom serialization, middlewares)

.faststream_gen/getting-started/asyncapi/index.md

@@ -0,0 +1,3 @@
+# AsyncAPI Documentation
+
+https://lancetnik.github.io/Propan/gettings_started/9_documentation/

.faststream_gen/getting-started/cli/index.md

@@ -0,0 +1,6 @@
+# CLI
+
+https://lancetnik.github.io/Propan/getting_started/2_cli/
+
++ multiprocessing
++ AsyncAPI documentation

.faststream_gen/getting-started/config/index.md

@@ -0,0 +1,3 @@
+# Settings and Environment Variables
+
+https://lancetnik.github.io/Propan/gettings_started/10_settings/

.faststream_gen/getting-started/context/index.md

@@ -0,0 +1,11 @@
+# Application Context
+
+Split Propan documentation page between articles
+
+Page:
+
+https://lancetnik.github.io/Propan/getting_started/5_dependency/2_context/
+
+Sources:
+
+https://github.com/Lancetnik/Propan/blob/main/docs/docs/en/getting_started/5_dependency/2_context.md

.faststream_gen/getting-started/dependencies/index.md

@@ -0,0 +1,7 @@
+# Dependencies
+
+References:
+
+* https://fastapi.tiangolo.com/tutorial/dependencies
+* https://lancetnik.github.io/Propan/getting_started/5_dependency/1_di-index/
+* https://lancetnik.github.io/FastDepends/tutorial

.faststream_gen/getting-started/index.md

@@ -1 +1,16 @@
-# First Steps
+# First Steps
+
+Inspiration: https://lancetnik.github.io/Propan/getting_started/1_quick-start/
+
+* Installation with various distributions
+
+* Simple application
+=== "Kafka"
+    app
+
+=== "RabbitMQ"
+    app
+
+* Broker docker container run
+
+* Run application

.faststream_gen/getting-started/lifespan/index.md

@@ -0,0 +1,6 @@
+# Lifespan Events
+
+References:
+
+* https://fastapi.tiangolo.com/advanced/events/
+* https://lancetnik.github.io/Propan/getting_started/6_lifespan/

.faststream_gen/getting-started/lifespan/test.md

@@ -0,0 +1,3 @@
+
+
+`TestApp` should be used after `TestClient` if it uses broker inside lifespan events

.faststream_gen/getting-started/logging.md

@@ -0,0 +1,3 @@
+# Application and Access Logging
+
+https://lancetnik.github.io/Propan/getting_started/8_logging/

.faststream_gen/getting-started/publishing/broker.md

@@ -0,0 +1,17 @@
+# Broker Publishing
+
+Easiest way to publish message
+
+Allows use a Broker like a publisher client in any applications.
+
+In the FastStream project this call not represented in the AsyncAPI scheme, so you can use it to send rarely-publishing messages (like startup/shutdown event).
+
+=== "Kafka"
+    ```python linenums="1"
+    {!> docs_src/getting_started/publishing/broker_kafka.py !}
+    ```
+
+=== "Rabbit"
+    ```python linenums="1"
+    {!> docs_src/getting_started/publishing/broker_rabbit.py !}
+    ```

.faststream_gen/getting-started/publishing/decorator.md

@@ -0,0 +1,29 @@
+# Publisher Decorator
+
+The second easy way to publish messages. Has an AsyncAPI representation.
+Suitable for fast application creation, but doesn't provide all testing features.
+
+Creates a structured DataPipeline unit with an input and output
+
+Subscriber and publisher decorators order has no matter, but can be used only with a functions decorated by a `subscriber` too.
+
+Uses the handler function return type annotation to cast function return before sending (be accurate with it)
+
+=== "Kafka"
+    ```python linenums="1"
+    {!> docs_src/getting_started/publishing/decorator_kafka.py !}
+    ```
+
+=== "Rabbit"
+    ```python linenums="1"
+    {!> docs_src/getting_started/publishing/decorator_rabbit.py !}
+    ```
+Can be used multiple times with the one function to broadcast function return
+
+```python
+@broker.subscriber("in")
+@broker.publisher("first-out")
+@broker.publisher("second-out")
+async def handle(msg) -> str:
+    return "Response"
+```

.faststream_gen/getting-started/publishing/direct.md

@@ -0,0 +1,24 @@
+# Publisher Direct Usage
+
+Full-featured way to publish messages (has AsyncAPI representation + testable feaures).
+Creates reusable Publisher object.
+
+Can be used directly to publush a message
+
+=== "Kafka"
+    ```python linenums="1"
+    {!> docs_src/getting_started/publishing/direct_kafka.py !}
+    ```
+
+=== "Rabbit"
+    ```python linenums="1"
+    {!> docs_src/getting_started/publishing/direct_rabbit.py !}
+    ```
+Suitable to publish different messages to different outputes at the same processing function
+
+```python
+@broker.subscriber("in")
+async def handle(msg) -> str:
+    await publisher1.publish("Response-1")
+    await publisher2.publish("Response-2")
+```

.faststream_gen/getting-started/publishing/index.md

@@ -0,0 +1,28 @@
+# Publishing Basics
+
+Broker agnostic, easy to use (even as a client in the not-FastStream apps)
+
+Several usecases
+
+* broker.publish
+* decorator
+* publisher object decorator
+* publisher object direct
+
+Allows to publish any JSON-serializable messages (python types, pydantic models, e.t.c.) or raw bytes.
+
+Automatically setups all required headers.
+
+Just setup a message and a routing key
+
+=== "Kafka"
+    ```python
+    async with KafkaBroker() as br:
+        await br.publish("message", "topic")
+    ```
+
+=== "Rabbit"
+    ```python
+    async with RabbitBroker() as br:
+        await br.publish("message", "queue")
+    ```

.faststream_gen/getting-started/publishing/object.md

@@ -0,0 +1,29 @@
+# Publisher Object
+
+Full-featured way to publish messages (has AsyncAPI representation + testable feaures).
+Creates reusable Publisher object.
+
+Can be used as a function decorator
+
+Subscriber and publisher decorators order has no matter, but can be used only with a functions decorated by a `subscriber` too.
+
+Also uses the handler function return type annotation to cast function return before sending (be accurate with it)
+
+=== "Kafka"
+    ```python linenums="1"
+    {!> docs_src/getting_started/publishing/object_kafka.py !}
+    ```
+
+=== "Rabbit"
+    ```python linenums="1"
+    {!> docs_src/getting_started/publishing/object_rabbit.py !}
+    ```
+Can be used multiple times with the one function to broadcast function return
+
+```python
+@publisher1
+@publisher2
+@broker.subscriber("in")
+async def handle(msg) -> str:
+    return "Response"
+```