Merge pull request #3 from pyper-dev/docs

Docs

Author: pyper-dev

.github/workflows/pages.yml renamed to .github/workflows/docs.yml

@@ -1,4 +1,4 @@
-name: Deploy Docs to GitHub Pages with Jekyll
+name: Docs
 
 on:
   push:
@@ -25,17 +25,23 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v4
+      - name: Setup Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.3'
+          bundler-cache: true
+          cache-version: 0
       - name: Setup Pages
+        id: pages
         uses: actions/configure-pages@v5
       - name: Build with Jekyll
-        uses: actions/jekyll-build-pages@v1
-        with:
-          source: ./docs
-          destination: ./_site
+        # Outputs to the './_site' directory by default
+        run: bundle exec jekyll build --baseurl "${{ steps.pages.outputs.base_path }}"
+        env:
+          JEKYLL_ENV: production
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3
 
-  # Deployment job
   deploy:
     environment:
       name: github-pages

.github/workflows/test.yml

@@ -7,12 +7,6 @@ on:
     paths:
       - "src/pyper/**"
       - "tests/**"
-  pull_request:
-    branches:
-      - main
-    paths:
-      - "src/pyper/**"
-      - "tests/**"
 
 jobs:
   test:

README.md

@@ -1,12 +1,10 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/pyper-dev/pyper/refs/heads/main/assets/pyper.png" alt="Pyper" style="width: 500px;">
+  <img src="https://raw.githubusercontent.com/pyper-dev/pyper/refs/heads/main/docs/src/assets/img/pyper.png" alt="Pyper" style="width: 500px;">
 </p>
 <p align="center" style="font-size: 1.5em;">
     <em>Concurrent Python made simple</em>
 </p>
 
-</p>
-
 <p align="center">
 <a href="https://github.com/pyper-dev/pyper/actions/workflows/test.yml" target="_blank">
     <img src="https://github.com/pyper-dev/pyper/actions/workflows/test.yml/badge.svg" alt="Test">
@@ -44,9 +42,9 @@ Install the latest version using `pip`:
 $ pip install python-pyper
 ```
 
-(Note that `python-pyper` is the pypi registered package)
+Note that `python-pyper` is the [pypi](https://pypi.org/project/python-pyper) registered package.
 
-## Example
+## Usage
 
 Let's simulate a pipeline that performs a series of transformations on some data. 
 
@@ -87,10 +85,7 @@ async def print_sum(data):
 
 async def main():
     # Define a pipeline of tasks using `pyper.task`
-    run = task(step1) \
-        >> task(step2, concurrency=20) \
-        >> task(step3, concurrency=20) \
-        & print_sum
+    run = task(step1) | task(step2, concurrency=20) | task(step3, concurrency=20) > print_sum
     await run(limit=20)
 
 
@@ -121,7 +116,7 @@ Having defined the logical operations we want to perform on our data as function
 
 ```python
 # Analogous to:
-# pipeline = task(step1) >> task(step2) >> task(step3)
+# pipeline = task(step1) | task(step2) | task(step3)
 async def pipeline(limit):
     for data in step1(limit):
         data = await step2(data)
@@ -130,7 +125,7 @@ async def pipeline(limit):
 
 
 # Analogous to:
-# run = pipeline & print_sum
+# run = pipeline > print_sum
 async def run(limit):
     await print_sum(pipeline(limit))
 
@@ -139,7 +134,7 @@ async def main():
     await run(20) # takes ~40 seconds
 ```
 
-Pyper uses the `>>` syntax as an intuitive representation of this input-output piping between tasks.
+Pyper uses the `|` (motivated by Unix's pipe operator) syntax as a representation of this input-output piping between tasks.
 
 </details>
 
@@ -266,9 +261,9 @@ def print_sum(data):
 
 def main():
     run = task(step1) \
-        >> task(step2, concurrency=20) \
-        >> task(step3, concurrency=20) \
-        & print_sum
+        | task(step2, concurrency=20) \
+        | task(step3, concurrency=20) \
+        > print_sum
     # Run synchronously
     run(limit=20)
 
@@ -283,9 +278,7 @@ A pipeline consisting of _at least one asynchronous function_ becomes an `AsyncP
 
 ## Examples
 
-To explore more of Pyper's features, see some real-world examples below:
-
-1. (_to do_)
+To explore more of Pyper's features, see some further [examples](https://pyper-dev.github.io/pyper/docs/Examples)
 
 ## Dependencies
 

docs/.gitignore

@@ -0,0 +1,10 @@
+_site/
+.sass-cache/
+.jekyll-cache/
+.jekyll-metadata
+
+.bundle/
+vendor/
+
+# GitHub pages does not need the lock file
+Gemfile.lock

docs/Gemfile

@@ -0,0 +1,7 @@
+source 'https://rubygems.org'
+
+gem "jekyll", "~> 4.3.4" # installed by `gem jekyll`
+gem "just-the-docs", "0.10.0" # pinned to the current release
+
+# Performance-booster for watching directories on Windows
+gem "wdm", "~> 0.1", :platforms => [:mingw, :x64_mingw, :mswin]

docs/_config.yml

@@ -0,0 +1,37 @@
+title: Pyper Docs
+description: Concurrent Python made simple
+theme: just-the-docs
+
+url: https://pyper-dev.github.io/pyper
+source: src
+
+color_scheme: dark
+
+logo: "/assets/img/pyper.png"
+favicon_ico: "/assets/img/favicon.ico"
+search_enabled: true
+nav_enabled: true
+
+search:
+  heading_level: 2
+  previews: 3
+  preview_words_before: 5
+  preview_words_after: 10
+  tokenizer_separator: /[\s/]+/
+  rel_url: true
+  button: false
+  focus_shortcut_key: 'k'
+
+# Aux links for the upper right navigation
+aux_links:
+  "GitHub":
+    - "//github.com/pyper-dev/pyper"
+aux_links_new_tab: true
+
+callouts:
+  info:
+    title: Info
+    color: blue
+  warning:
+    title: Warning
+    color: yellow

docs/src/404.md

@@ -0,0 +1,8 @@
+---
+layout: default
+permalink: /404.html
+---
+
+# 404
+
+This page wasn't found

docs/src/assets/img/favicon.ico

@@ -0,0 +1,11 @@
+---
+title: API Reference
+nav_order: 4
+layout: page
+---
+
+# API Reference
+
+All pipelines in Pyper are created with the `pyper.task` decorator.
+
+See [Task Parameters](../UserGuide/TaskParameters)