update docs and readme

Author: RichardZhu2

README.md

@@ -22,11 +22,11 @@
 
 ---
 
-Pyper is a comprehensive framework for concurrent and parallel data-processing, based on functional programming patterns. Used for 🌐 **Data Collection**, 🔀 **ETL Systems**, and general-purpose 🛠️ **Python Scripting**
+Pyper is a flexible framework for concurrent and parallel data-processing, based on functional programming patterns. Used for 🔀 **ETL Systems**, ⚙️ **Data Microservices**, and 🌐 **Data Collection**
 
 See the [Documentation](https://pyper-dev.github.io/pyper/)
 
-Key features:
+**Key features:**
 
 * 💡**Intuitive API**: Easy to learn, easy to think about. Implements clean abstractions to seamlessly unify threaded, multiprocessed, and asynchronous work.
 * 🚀 **Functional Paradigm**: Python functions are the building blocks of data pipelines. Let's you write clean, reusable code naturally.
@@ -99,7 +99,7 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-Pyper provides an elegant abstraction of the execution of each function via `pyper.task`, allowing you to focus on building out the **logical** functions of your program. In the `main` function:
+Pyper provides an elegant abstraction of the execution of each task, allowing you to focus on building out the **logical** functions of your program. In the `main` function:
 
 * `pipeline` defines a function; this takes the parameters of its first task (`get_data`) and yields each output from its last task (`step3`)
 * Tasks are piped together using the `|` operator (motivated by Unix's pipe operator) as a syntactic representation of passing inputs/outputs between tasks.
@@ -114,7 +114,7 @@ In the pipeline, we are executing three different types of work:
 
 `task` acts as one intuitive API for unifying the execution of each different type of function.
 
-Each task submits their outputs to the next task within the pipeline via queue-based data structures, which is the mechanism underpinning how concurrency and parallelism are achieved. See the [docs](https://pyper-dev.github.io/pyper/docs/UserGuide/BasicConcepts) for a breakdown of what a pipeline looks like under the hood.
+Each task has workers that submit outputs to the next task within the pipeline via queue-based data structures; this is the mechanism underpinning how concurrency and parallelism are achieved. See the [docs](https://pyper-dev.github.io/pyper/docs/UserGuide/BasicConcepts) for a breakdown of what a pipeline looks like under the hood.
 
 ---
 

docs/src/assets/img/hint1.png

@@ -75,14 +75,14 @@ The correct way to optimize the performance of CPU-bound tasks is through parall
 # Okay
 @task(workers=10, multiprocess=True)
 def long_computation(data: int):
-    for i in range(10_000_000):
+    for i in range(1, 1_000_000):
         data *= i
     return data
 
 # Bad -- cannot benefit from concurrency
 @task(workers=10)
 def long_computation(data: int):
-    for i in range(10_000_000):
+    for i in range(1, 1_000_000):
         data *= i
     return data
 ```
@@ -150,7 +150,7 @@ The correct pattern is generally to define functions which take these resources
 from aiohttp import ClientSession
 from pyper import task
 
-async def list_user_ids(session: ClientSession) -> list:
+async def list_user_ids(session: ClientSession) -> list[int]:
     async with session.get("/users") as r:
         return await r.json()
 
@@ -163,7 +163,7 @@ When defining a pipeline, these additional arguments are plugged into tasks usin
 
 ```python
 async def main():
-    async with ClientSession("http://localhost:8000") as session:
+    async with ClientSession("http://localhost:8000/api") as session:
         user_data_pipeline = (
             task(list_user_ids, branch=True, bind=task.bind(session=session))
             | task(fetch_user_data, workers=10, bind=task.bind(session=session))
@@ -183,7 +183,7 @@ from pyper import task, AsyncPipeline
 
 def user_data_pipeline(session: ClientSession) -> AsyncPipeline:
 
-    async def list_user_ids() -> list:
+    async def list_user_ids() -> list[int]:
         async with session.get("/users") as r:
             return await r.json()
 
@@ -197,11 +197,11 @@ def user_data_pipeline(session: ClientSession) -> AsyncPipeline:
     )
 ```
 
-Now `user_data_pipeline` constructs a self-contained sata-flow, which can be reused without having to define its internal pipeline everytime.
+Now `user_data_pipeline` constructs a self-contained data-flow, which can be reused without having to define its internal pipeline everytime.
 
 ```python
 async def main():
-    async with ClientSession("http://localhost:8000") as session:
+    async with ClientSession("http://localhost:8000/api") as session:
         run = (
             user_data_pipeline(session)
             | task(write_to_file, join=True)

docs/src/assets/img/hint2.png

@@ -89,7 +89,13 @@ if __name__ == "__main__":
 ```
 
 {: .info}
-Pyper comes with fantastic IDE intellisense support which understands these operators, and will always show you which variables are `Pipeline` or `AsyncPipeline` objects; this also preserves type hints from your own functions, showing you the parameter and return type specs for each pipeline or consumer
+Pyper comes with fantastic intellisense support which understands these operators and preserves parameter/return type hints from user-defined functions
+
+<img src="../../assets/img/hint1.png" alt="Type Hint" style="width: 500; height: auto;">
+
+<img src="../../assets/img/hint2.png" alt="Type Hint" style="width: 500; height: auto;">
+
+<img src="../../assets/img/hint3.png" alt="Type Hint" style="width: 500; height: auto;">
 
 ## Nested Pipelines
 

docs/src/assets/img/hint3.png

@@ -41,10 +41,13 @@ The Python package space has great support for achieving
 
 However, the solutions for _general-purpose_ data processing are less established.
 
-Pyper aims to offer a comprehensive framework for concurrent and parallel data-processing in Python, designed with the following goals in mind:
+{: .text-green-200}
+**Pyper aims to offer a flexible framework for concurrent and parallel data-processing in Python**
+
+It is designed with the following goals in mind:
 
 * **Unified API**: Combine threads, processes and async code using one intuitive pattern
-* **Functional Paradigm**: Data pipelines compose together flexibly as functions
+* **Functional Paradigm**: Data pipelines compose together straightforwardly as functions
 * **Lazy Execution**: Built from the ground up to support generators, and provides mechanisms for fine-grained memory control
 * **Error Handling**: Data flows fail fast, even in long-running threads, and propagate their errors cleanly
 * **Complex Data Flows**: Data pipelines support branching/joining data flows, as well as sharing contexts/resources between tasks
@@ -61,6 +64,6 @@ $ pip install python-pyper
 
 ## Where Next?
 
-* Check out the 📖 **[User Guide](./docs/UserGuide/)** to get started with Pyper
+* Check out the 📖 **[User Guide](./docs/UserGuide/BasicConcepts)** to get started with Pyper
 
 * See some 🎯 **[Examples](./docs/Examples/)** of possible use cases