add ci for the docs

Author: egorsmkv

.github/workflows/mkdocs.yml

@@ -0,0 +1,64 @@
+name: Build and Deploy MkDocs
+
+on:
+  push:
+    branches:
+      - master
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/mkdocs.yml
+  pull_request:
+    paths:
+      - docs/**
+      - mkdocs.yml
+      - .github/workflows/mkdocs.yml
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install MkDocs
+        run: python -m pip install mkdocs
+
+      - name: Build docs
+        run: mkdocs build --strict
+
+      - name: Upload Pages artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
+
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

docs/examples.md

@@ -0,0 +1,254 @@
+# Examples
+
+This page shows practical ways to use `rsloop`.
+
+All examples use normal Python `asyncio` patterns. The difference is that `rsloop` provides the event loop implementation.
+
+## Run one coroutine
+
+This is the simplest starting point:
+
+```python
+import rsloop
+
+
+async def main() -> None:
+    print("hello from rsloop")
+
+
+rsloop.run(main())
+```
+
+Use this style when your program has one main async entry point.
+
+## Create tasks inside the loop
+
+This looks almost the same as standard `asyncio`:
+
+```python
+import asyncio
+import rsloop
+
+
+async def worker(name: str) -> str:
+    await asyncio.sleep(0.1)
+    return f"{name} done"
+
+
+async def main() -> None:
+    task1 = asyncio.create_task(worker("first"))
+    task2 = asyncio.create_task(worker("second"))
+    results = await asyncio.gather(task1, task2)
+    print(results)
+
+
+rsloop.run(main())
+```
+
+If your app already uses `asyncio.create_task(...)`, `await`, and `gather(...)`, moving to `rsloop` is usually straightforward.
+
+## Create a loop manually
+
+Manual loop creation is useful when you want explicit setup and cleanup:
+
+```python
+import asyncio
+import rsloop
+
+
+async def main() -> None:
+    print("running on", type(asyncio.get_running_loop()).__name__)
+
+
+loop = rsloop.new_event_loop()
+asyncio.set_event_loop(loop)
+try:
+    loop.run_until_complete(main())
+finally:
+    asyncio.set_event_loop(None)
+    loop.close()
+```
+
+Use this style if your program manages the loop lifecycle itself.
+
+## Schedule callbacks
+
+`rsloop.Loop` supports the familiar callback APIs:
+
+```python
+import rsloop
+
+
+loop = rsloop.new_event_loop()
+
+
+def say(message: str) -> None:
+    print(message)
+    loop.stop()
+
+
+loop.call_later(0.5, say, "timer fired")
+loop.run_forever()
+loop.close()
+```
+
+This is useful when reading older `asyncio` code that still uses callbacks instead of only coroutines.
+
+## Work with raw sockets
+
+You can use socket helpers directly on the running loop:
+
+```python
+import asyncio
+import socket
+import rsloop
+
+
+async def main() -> None:
+    loop = asyncio.get_running_loop()
+    left, right = socket.socketpair()
+    left.setblocking(False)
+    right.setblocking(False)
+
+    try:
+        await loop.sock_sendall(left, b"ping")
+        data = await loop.sock_recv(right, 4)
+        print(data.decode())
+    finally:
+        left.close()
+        right.close()
+
+
+rsloop.run(main())
+```
+
+Use this style when you need lower-level control than streams provide.
+
+## Start a TCP server
+
+`rsloop` supports the normal protocol and transport style:
+
+```python
+import asyncio
+import rsloop
+
+
+class EchoProtocol(asyncio.Protocol):
+    def connection_made(self, transport: asyncio.BaseTransport) -> None:
+        self.transport = transport
+
+    def data_received(self, data: bytes) -> None:
+        self.transport.write(data.upper())
+
+
+async def main() -> None:
+    loop = asyncio.get_running_loop()
+    server = await loop.create_server(EchoProtocol, "127.0.0.1", 9000)
+    try:
+        print("serving on 127.0.0.1:9000")
+        await asyncio.sleep(60)
+    finally:
+        server.close()
+        await server.wait_closed()
+
+
+rsloop.run(main())
+```
+
+This is a good fit when your project already uses `asyncio.Protocol`.
+
+## Use streams
+
+Because `rsloop` can patch stream helpers, high-level stream code can stay familiar:
+
+```python
+import asyncio
+import rsloop
+
+
+async def handle_client(reader: asyncio.StreamReader, writer: asyncio.StreamWriter) -> None:
+    data = await reader.read(100)
+    writer.write(data.upper())
+    await writer.drain()
+    writer.close()
+    await writer.wait_closed()
+
+
+async def main() -> None:
+    server = await asyncio.start_server(handle_client, "127.0.0.1", 9001)
+    try:
+        reader, writer = await asyncio.open_connection("127.0.0.1", 9001)
+        writer.write(b"hello")
+        await writer.drain()
+        print((await reader.read(100)).decode())
+        writer.close()
+        await writer.wait_closed()
+    finally:
+        server.close()
+        await server.wait_closed()
+
+
+rsloop.run(main())
+```
+
+This is often the easiest path for developers who already use high-level `asyncio` streams.
+
+## Run blocking work in an executor
+
+Not everything has to be async:
+
+```python
+import asyncio
+import rsloop
+
+
+def blocking_sum() -> int:
+    return sum(range(100000))
+
+
+async def main() -> None:
+    loop = asyncio.get_running_loop()
+    result = await loop.run_in_executor(None, blocking_sum)
+    print(result)
+
+
+rsloop.run(main())
+```
+
+Use this when you must call blocking Python code without freezing the event loop.
+
+## Run a subprocess
+
+`rsloop` also supports subprocess workflows:
+
+```python
+import asyncio
+import rsloop
+import sys
+
+
+async def main() -> None:
+    proc = await asyncio.create_subprocess_exec(
+        sys.executable,
+        "-c",
+        "print('hello from child')",
+        stdout=asyncio.subprocess.PIPE,
+    )
+    stdout, _ = await proc.communicate()
+    print(stdout.decode().strip())
+
+
+rsloop.run(main())
+```
+
+This is useful for scripts, tooling, and service code that needs to call external programs.
+
+## Where to find bigger examples
+
+For fuller examples, read the repository files in `examples/`:
+
+- `01_basics.py`
+- `02_fd_and_sockets.py`
+- `03_streams.py`
+- `04_unix_and_accepted_socket.py`
+- `05_pipes_signals_subprocesses.py`

docs/getting-started.md

@@ -105,3 +105,5 @@ The `examples/` directory is the best hands-on tour of the project:
 - `examples/05_pipes_signals_subprocesses.py`: pipes, signals, and subprocesses
 
 If you are new to lower-level `asyncio` features, start with `01_basics.py` and `03_streams.py`.
+
+There is also a shorter docs page with copy-paste snippets in [Examples](examples.md).

docs/index.md

@@ -27,6 +27,25 @@ That means:
 - `rsloop.Loop` is the main event loop class.
 - Importing `rsloop` also installs a few compatibility patches so it fits better into normal `asyncio` code.
 
+## For Intermediate Python Developers
+
+If you already use `asyncio` comfortably, these are the main things worth knowing early:
+
+- `rsloop` tries to keep the standard `asyncio` mental model, not invent a new one.
+- The Python package is mostly a thin wrapper around a Rust extension built with PyO3.
+- `rsloop.run(...)` behaves like a focused `asyncio.run(...)` helper that ensures an `rsloop` loop is actually being used.
+- Importing `rsloop` can monkeypatch parts of `asyncio`, especially `set_event_loop(...)` and optionally stream helpers such as `open_connection(...)` and `start_server(...)`.
+- The runtime model is hybrid: Python coroutines still run as Python code, while lower-level loop coordination and parts of the I/O stack are handled in Rust.
+- Compatibility is a project goal, but not every `asyncio` edge case is identical yet, especially around TLS and some transport internals.
+
+If you want to read code instead of only using the package, a good path is:
+
+1. `python/rsloop/_run.py`
+2. `python/rsloop/_loop_compat.py`
+3. `src/lib.rs`
+4. `src/python_api.rs`
+5. `src/loop_core.rs`
+
 ## What is inside this repository?
 
 At a high level, the repository has five parts:
@@ -55,6 +74,7 @@ rsloop.run(main())
 ## Recommended reading order
 
 - Start with [Getting Started](getting-started.md) if you want to use the package.
+- Read [Examples](examples.md) if you want copy-paste usage patterns.
 - Read [How It Works](how-it-works.md) if you want the big picture.
 - Read [Project Structure](project-structure.md) if you want to explore the codebase.
 - Read [Development](development.md) if you want to build or test the project locally.

mkdocs.yml

@@ -6,6 +6,7 @@ theme:
 nav:
   - Home: index.md
   - Getting Started: getting-started.md
+  - Examples: examples.md
   - How It Works: how-it-works.md
   - Project Structure: project-structure.md
   - Development: development.md